Chamilo\CoreBundle\Controller\CourseMaintenanceController

Complexity

Total Complexity

840

Size/Duplication

Total Lines	3840
Duplicated Lines	0 %

Importance

Changes	6
Bugs	2	Features	0

62 Methods

Rating	Name	Duplication	Size	Complexity
A	importOptions()	0	14	1
B	importUpload()	0	39	7
B	importServerPick()	0	23	8
A	importResources()	0	29	3
B	cc13Import()	0	49	6
A	zipHasMoodleBackupXml()	0	14	3
C	importDiagnose()	0	101	13
F	resolveItemLabel()	0	133	40
C	snapshotResources()	0	32	13
A	loadMoodleCourseOrFail()	0	21	6
A	zipHasCourseInfoDat()	0	17	5
A	findBucket()	0	4	4
F	buildResourceTreeForVue()	0	267	73
B	buildSelectionFromTypes()	0	54	11
F	buildForumTreeForVue()	0	206	68
B	copyExecute()	0	72	9
A	resolveBackupPath()	0	15	4
A	moodleExportOptions()	0	37	1
F	buildCc13Preview()	0	60	17
A	isMoodleByExt()	0	4	1
C	deleteCourse()	0	63	13
A	cc13ExportOptions()	0	9	1
A	snapshotForumCounts()	0	10	3
A	getImportSource()	0	9	2
A	normalizeSelectedTools()	0	31	4
A	mapSameNameOption()	0	18	5
A	firstExistingKey()	0	9	5
B	deincomplete()	0	22	7
A	cloneCourseWithBuckets()	0	16	3
C	restoreMoodle()	0	87	12
F	normalizeBucketsForRestorer()	0	129	23
A	recycleOptions()	0	12	1
B	runBucketRestore()	0	72	9
A	setDebugFromRequest()	0	16	6
F	filterLegacyCourseBySelection()	0	347	135
A	copyOptions()	0	23	3
A	findBucketKey()	0	4	2
F	loadLegacyCourseForAnyBackup()	0	82	20
A	copyResources()	0	43	3
B	moodleExportResources()	0	83	8
B	recycleExecute()	0	44	8
F	decodeCourseInfo()	0	173	34
A	getSkipTypeKeys()	0	15	1
F	cc13ExportExecute()	0	89	16
A	objectEntity()	0	7	3
B	intersectBucketByIds()	0	12	7
A	getDefaultTypeTitles()	0	29	1
F	moodleExportExecute()	0	123	28
B	cc13ExportResources()	0	38	9
B	filterCourseResources()	0	52	8
A	logDebug()	0	23	6
C	expandCc13SelectionFromCategories()	0	35	16
A	isSelectableItem()	0	12	4
F	importRestore()	0	162	27
D	bucketKeyCandidates()	0	32	10
C	readCourseInfoFromZip()	0	81	14
F	inferToolsFromSelection()	0	55	31
D	buildLinkTreeForVue()	0	89	18
D	buildExtra()	0	74	22
A	recycleResources()	0	18	2
A	cc13ExportDownload()	0	21	4
C	normalizeTypeKey()	0	57	13

<?php

/* For licensing terms, see /license.txt */

declare(strict_types=1);

namespace Chamilo\CoreBundle\Controller;

use Chamilo\CoreBundle\Repository\Node\UserRepository;
use Chamilo\CourseBundle\Component\CourseCopy\CommonCartridge\Builder\Cc13Capabilities;
use Chamilo\CourseBundle\Component\CourseCopy\CommonCartridge\Builder\Cc13Export;
use Chamilo\CourseBundle\Component\CourseCopy\CommonCartridge\Import\Imscc13Import;
use Chamilo\CourseBundle\Component\CourseCopy\CourseArchiver;
use Chamilo\CourseBundle\Component\CourseCopy\CourseBuilder;
use Chamilo\CourseBundle\Component\CourseCopy\CourseRecycler;
use Chamilo\CourseBundle\Component\CourseCopy\CourseRestorer;
use Chamilo\CourseBundle\Component\CourseCopy\CourseSelectForm;
use Chamilo\CourseBundle\Component\CourseCopy\Moodle\Builder\MoodleExport;
use Chamilo\CourseBundle\Component\CourseCopy\Moodle\Builder\MoodleImport;
use CourseManager;
use Doctrine\ORM\EntityManagerInterface;
use RuntimeException;
use stdClass;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\{BinaryFileResponse, JsonResponse, Request, ResponseHeaderBag};
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Http\Attribute\IsGranted;
use Throwable;

use const ARRAY_FILTER_USE_BOTH;
use const JSON_UNESCAPED_SLASHES;
use const JSON_UNESCAPED_UNICODE;
use const PATHINFO_EXTENSION;

#[IsGranted('ROLE_TEACHER')]
#[Route('/course_maintenance/{node}', name: 'cm_', requirements: ['node' => '\d+'])]
class CourseMaintenanceController extends AbstractController
{
    /**
     * @var bool Debug flag (true by default). Toggle via ?debug=0|1 or X-Debug: 0|1
     */
    private bool $debug = true;

    #[Route('/import/options', name: 'import_options', methods: ['GET'])]
    public function importOptions(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);
        $this->logDebug('[importOptions] called', ['node' => $node, 'debug' => $this->debug]);

        return $this->json([
            'sources' => ['local', 'server'],
            'importOptions' => ['full_backup', 'select_items'],
            'sameName' => ['skip', 'rename', 'overwrite'],
            'defaults' => [
                'importOption' => 'full_backup',
                'sameName' => 'rename',
                'sameFileNameOption' => 2,
            ],
        ]);
    }

    #[Route('/import/upload', name: 'import_upload', methods: ['POST'])]
    public function importUpload(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        $file = $req->files->get('file');
        if (!$file || !$file->isValid()) {
            return $this->json(['error' => 'Invalid upload'], 400);
        }

        $maxBytes = 1024 * 1024 * 512;
        if ($file->getSize() > $maxBytes) {
            return $this->json(['error' => 'File too large'], 413);
        }

        $allowed = ['zip', 'mbz', 'gz', 'tgz'];
        $ext = strtolower($file->guessExtension() ?: pathinfo($file->getClientOriginalName(), PATHINFO_EXTENSION));
        if (!\in_array($ext, $allowed, true)) {
            return $this->json(['error' => 'Unsupported file type'], 415);
        }

        $this->logDebug('[importUpload] received', [
            'original_name' => $file->getClientOriginalName(),
            'size' => $file->getSize(),
            'mime' => $file->getClientMimeType(),
        ]);

        $backupId = CourseArchiver::importUploadedFile($file->getRealPath());
        if (false === $backupId) {
            $this->logDebug('[importUpload] archive dir not writable');

            return $this->json(['error' => 'Archive directory is not writable'], 500);
        }

        $this->logDebug('[importUpload] stored', ['backupId' => $backupId]);

        return $this->json([
            'backupId' => $backupId,
            'filename' => $file->getClientOriginalName(),
        ]);
    }

    #[Route('/import/server', name: 'import_server_pick', methods: ['POST'])]
    public function importServerPick(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);
        $payload = json_decode($req->getContent() ?: '{}', true);

        $filename = basename((string) ($payload['filename'] ?? ''));
        if ('' === $filename || preg_match('/[\/\\\]/', $filename)) {
            return $this->json(['error' => 'Invalid filename'], 400);
        }

        $path = rtrim(CourseArchiver::getBackupDir(), '/').'/'.$filename;
        $realBase = realpath(CourseArchiver::getBackupDir());
        $realPath = realpath($path);
        if (!$realBase || !$realPath || 0 !== strncmp($realBase, $realPath, \strlen($realBase)) || !is_file($realPath)) {
            $this->logDebug('[importServerPick] file not found or outside base', ['path' => $path]);

            return $this->json(['error' => 'File not found'], 404);
        }

        $this->logDebug('[importServerPick] ok', ['backupId' => $filename]);

        return $this->json(['backupId' => $filename, 'filename' => $filename]);
    }

    #[Route(
        '/import/{backupId}/resources',
        name: 'import_resources',
        requirements: ['backupId' => '.+'],
        methods: ['GET']
    )]
    public function importResources(int $node, string $backupId, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);
        $mode = strtolower((string) $req->query->get('mode', 'auto')); // 'auto' | 'dat' | 'moodle'

        $course = $this->loadLegacyCourseForAnyBackup($backupId, $mode === 'dat' ? 'chamilo' : $mode);

        $this->logDebug('[importResources] course loaded', [
            'has_resources' => \is_array($course->resources ?? null),
            'keys' => array_keys((array) ($course->resources ?? [])),
        ]);

        $tree = $this->buildResourceTreeForVue($course);

        $warnings = [];
        if (empty($tree)) {
            $warnings[] = 'Backup has no selectable resources.';
        }

        return $this->json([
            'tree'     => $tree,
            'warnings' => $warnings,
            'meta'     => ['import_source' => $course->resources['__meta']['import_source'] ?? null],
        ]);
    }

    #[Route(
        '/import/{backupId}/restore',
        name: 'import_restore',
        requirements: ['backupId' => '.+'],
        methods: ['POST']
    )]
    public function importRestore(
        int $node,
        string $backupId,
        Request $req,
        EntityManagerInterface $em
    ): JsonResponse {
        $this->setDebugFromRequest($req);

        error_log('COURSE_DEBUG: [importRestore] begin -> ' . json_encode([
                'node'     => $node,
                'backupId' => $backupId,
            ], JSON_UNESCAPED_SLASHES));

        try {
            // Disable profiler & SQL logger for performance
            if ($this->container->has('profiler')) {
                $profiler = $this->container->get('profiler');
                if ($profiler instanceof \Symfony\Component\HttpKernel\Profiler\Profiler) {
                    $profiler->disable();
                }
            }
            if ($this->container->has('doctrine')) {
                $emDoctrine = $this->container->get('doctrine')->getManager();
                if ($emDoctrine && $emDoctrine->getConnection()) {
                    $emDoctrine->getConnection()->getConfiguration()->setSQLLogger(null);
                }
            }

            // Parse payload
            $payload = json_decode($req->getContent() ?: '{}', true) ?: [];
            $mode               = strtolower((string) ($payload['mode'] ?? 'auto'));         // 'auto' | 'dat' | 'moodle'
            $importOption       = (string)  ($payload['importOption'] ?? 'full_backup');      // 'full_backup' | 'select_items'
            $sameFileNameOption = (int)     ($payload['sameFileNameOption'] ?? 2);            // 0 skip | 1 overwrite | 2 rename
            $selectedResources  = (array)   ($payload['resources'] ?? []);                    // map type -> [ids]
            $selectedTypes      = array_map('strval', (array) ($payload['selectedTypes'] ?? []));

            error_log('COURSE_DEBUG: [importRestore] input -> ' . json_encode([
                    'mode'               => $mode,
                    'importOption'       => $importOption,
                    'sameFileNameOption' => $sameFileNameOption,
                    'selectedTypes.count'=> count($selectedTypes),
                    'hasResourcesMap'    => !empty($selectedResources),
                ], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE));

            // Load snapshot (keep same source mode as GET /resources)
            $course = $this->loadLegacyCourseForAnyBackup($backupId, $mode === 'dat' ? 'chamilo' : $mode);
            if (!\is_object($course) || !\is_array($course->resources ?? null)) {
                return $this->json(['error' => 'Backup has no resources'], 400);
            }

            // Quick counts for logging
            $counts = [];
            foreach ((array) $course->resources as $k => $bag) {
                if ($k === '__meta') { continue; }
                $counts[$k] = \is_array($bag) ? \count($bag) : 0;
            }
            error_log('COURSE_DEBUG: [importRestore] snapshot.counts -> ' . json_encode($counts, JSON_UNESCAPED_SLASHES));

            // Detect source (Moodle vs non-Moodle)
            $importSource = strtolower((string) ($course->resources['__meta']['import_source'] ?? $mode));
            $isMoodle     = ($importSource === 'moodle');
            error_log('COURSE_DEBUG: [importRestore] detected import source -> ' . json_encode([
                    'import_source' => $importSource,
                    'isMoodle'      => $isMoodle,
                ], JSON_UNESCAPED_SLASHES));

            // Build requested buckets list
            if ($importOption === 'select_items') {
                if (!empty($selectedResources)) {
                    $requested = array_keys(array_filter(
                        $selectedResources,
                        static fn ($ids) => \is_array($ids) && !empty($ids)
                    ));
                } elseif (!empty($selectedTypes)) {
                    $requested = $selectedTypes;
                } else {
                    return $this->json(['error' => 'No resources selected'], 400);
                }
            } else {
                // full_backup => take all snapshot keys (except __meta)
                $requested = array_keys(array_filter(
                    (array) $course->resources,
                    static fn ($k) => $k !== '__meta',
                    ARRAY_FILTER_USE_KEY
                ));
            }
            // Normalize for case
            $requested = array_values(array_unique(array_map(static fn ($k) => strtolower((string) $k), $requested)));
            error_log('COURSE_DEBUG: [importRestore] requested -> ' . json_encode($requested, JSON_UNESCAPED_SLASHES));

            // Non-Moodle path (use CourseRestorer directly)
            if (!$isMoodle) {
                error_log('COURSE_DEBUG: [importRestore] non-Moodle path -> CourseRestorer');

                if ($importOption === 'select_items') {
                    $filtered = clone $course;
                    $filtered->resources = ['__meta' => $course->resources['__meta'] ?? []];
                    foreach ($requested as $rk) {
                        if (isset($course->resources[$rk])) {
                            $filtered->resources[$rk] = $course->resources[$rk];
                        }
                    }
                    $course = $filtered;
                }

                $restorer = new CourseRestorer($course);
                // Restorer understands 0/1/2 for (skip/overwrite/rename)
                $restorer->set_file_option($sameFileNameOption);
                if (method_exists($restorer, 'setDebug')) {
                    $restorer->setDebug($this->debug ?? false);
                }

                $t0 = microtime(true);
                $restorer->restore();
                $ms = (int) round((microtime(true) - $t0) * 1000);

                CourseArchiver::cleanBackupDir();

                $dstId = (int) ($restorer->destination_course_info['real_id'] ?? 0);
                error_log('COURSE_DEBUG: [importRestore] non-Moodle DONE ms=' . $ms . ' dstId=' . $dstId);

                return $this->json([
                    'ok'          => true,
                    'message'     => 'Import finished',
                    'redirectUrl' => sprintf('/course/%d/home?sid=0&gid=0', $dstId ?: (int) (api_get_course_info()['real_id'] ?? 0)),
                ]);
            }

            // Moodle path (documents via MoodleImport, rest via CourseRestorer)
            $cacheDir   = (string) $this->getParameter('kernel.cache_dir');
            $backupPath = rtrim($cacheDir, '/').'/course_backups/'.$backupId;

            $stats = $this->restoreMoodle(
                $backupPath,
                $course,
                $requested,
                $sameFileNameOption,
                $em
            );

            return $this->json([
                'ok'          => true,
                'message'     => 'Moodle import finished',
                'stats'       => $stats,
                'redirectUrl' => sprintf('/course/%d/home?sid=0&gid=0', (int) (api_get_course_info()['real_id'] ?? 0)),
            ]);

        } catch (\Throwable $e) {
            error_log('COURSE_DEBUG: [importRestore] ERROR -> ' . $e->getMessage() . ' @ ' . $e->getFile() . ':' . $e->getLine());
            return $this->json([
                'error'   => 'Restore failed: ' . $e->getMessage(),
                'details' => method_exists($e, 'getTraceAsString') ? $e->getTraceAsString() : null,
            ], 500);
        } finally {
            // Defensive cleanup
            try { CourseArchiver::cleanBackupDir(); } catch (\Throwable) {}

Consider moving this CATCH statement to a new line.

        }
    }

    /**
     * Single helper for Moodle branch:
     * - Restore documents from MBZ (needs ZIP path and MoodleImport).
     * - Restore remaining buckets using CourseRestorer over the filtered snapshot.
     */
    private function restoreMoodle(
        string $backupPath,
        object $course,
        array $requested,
        int $sameFileNameOption,
        EntityManagerInterface $em
    ): array {
        $stats = [];
        $ci  = api_get_course_info();
        $cid = (int) ($ci['real_id'] ?? 0);
        $sid = 0;

        // 1) Documents (if requested)
        $wantsDocs = \in_array('document', $requested, true) || \in_array('documents', $requested, true);
        if ($wantsDocs) {
            $tag = substr(dechex(random_int(0, 0xFFFFFF)), 0, 6);
            error_log(sprintf('MBZ[%s] RESTORE_DOCS: begin path=%s', $tag, $backupPath));

            $importer = new MoodleImport(debug: $this->debug ?? false);

            $courseForDocs = clone $course;
            $courseForDocs->resources = [
                '__meta'   => $course->resources['__meta'] ?? [],
                'document' => $course->resources['document'] ?? [],
            ];

            $t0 = microtime(true);
            if (method_exists($importer, 'restoreDocuments')) {
                $res = $importer->restoreDocuments(
                    $backupPath,
                    $em,
                    $cid,
                    $sid,
                    (int) $sameFileNameOption,
                    $courseForDocs
                );
                $stats['documents'] = $res ?? ['imported' => 0];
            } else {
                error_log('MBZ['.$tag.'] RESTORE_DOCS: restoreDocuments() not found on importer');
                $stats['documents'] = ['imported' => 0, 'notes' => ['restoreDocuments() missing']];
            }
            $ms = (int) round((microtime(true) - $t0) * 1000);
            error_log(sprintf('MBZ[%s] RESTORE_DOCS: end ms=%d', $tag, $ms));
        }

        // 2) Remaining buckets via CourseRestorer (links, forums, announcements, attendance, etc.)
        $restRequested = array_values(array_filter($requested, static function ($k) {
            $k = strtolower((string) $k);
            return $k !== 'document' && $k !== 'documents';
        }));
        if (empty($restRequested)) {
            return $stats;
        }

        $filtered = clone $course;
        $filtered->resources = ['__meta' => $course->resources['__meta'] ?? []];
        foreach ($restRequested as $rk) {
            if (isset($course->resources[$rk])) {
                $filtered->resources[$rk] = $course->resources[$rk];
            }
        }
        // Simple dependency example: include Link_Category when links are requested
        if (\in_array('link', $restRequested, true) || \in_array('links', $restRequested, true)) {
            if (isset($course->resources['Link_Category'])) {
                $filtered->resources['Link_Category'] = $course->resources['Link_Category'];
            }
        }

        error_log('COURSE_DEBUG: [restoreMoodle] restorer.keys -> ' . json_encode(array_keys((array) $filtered->resources), JSON_UNESCAPED_SLASHES));

        $restorer = new CourseRestorer($filtered);
        $restorer->set_file_option($sameFileNameOption);
        if (method_exists($restorer, 'setDebug')) {
            $restorer->setDebug($this->debug ?? false);
        }

        $t1 = microtime(true);
        $restorer->restore();
        $ms = (int) round((microtime(true) - $t1) * 1000);
        error_log('COURSE_DEBUG: [restoreMoodle] restorer DONE ms=' . $ms);

        $stats['restored_tools'] = array_values(array_filter(
            array_keys((array) $filtered->resources),
            static fn($k) => $k !== '__meta'
        ));

        return $stats;
    }

    #[Route('/copy/options', name: 'copy_options', methods: ['GET'])]
    public function copyOptions(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        $current = api_get_course_info();
        $courseList = CourseManager::getCoursesFollowedByUser(api_get_user_id());

        $courses = [];
        foreach ($courseList as $c) {
            if ((int) $c['real_id'] === (int) $current['real_id']) {
                continue;
            }
            $courses[] = ['id' => (string) $c['code'], 'code' => $c['code'], 'title' => $c['title']];
        }

        return $this->json([
            'courses' => $courses,
            'defaults' => [
                'copyOption' => 'full_copy',
                'includeUsers' => false,
                'resetDates' => true,
                'sameFileNameOption' => 2,
            ],
        ]);
    }

    #[Route('/copy/resources', name: 'copy_resources', methods: ['GET'])]
    public function copyResources(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);
        $sourceCourseCode = trim((string) $req->query->get('sourceCourseId', ''));
        if ('' === $sourceCourseCode) {
            return $this->json(['error' => 'Missing sourceCourseId'], 400);
        }

        $cb = new CourseBuilder();
        $cb->set_tools_to_build([
            'documents',
            'forums',
            'tool_intro',
            'links',
            'quizzes',
            'quiz_questions',
            'assets',
            'surveys',
            'survey_questions',
            'announcement',
            'events',
            'course_descriptions',
            'glossary',
            'wiki',
            'thematic',
            'attendance',
            'works',
            'gradebook',
            'learnpath_category',
            'learnpaths',
        ]);

        $course = $cb->build(0, $sourceCourseCode);

        $tree = $this->buildResourceTreeForVue($course);

        $warnings = [];
        if (empty($tree)) {
            $warnings[] = 'Source course has no resources.';
        }

        return $this->json(['tree' => $tree, 'warnings' => $warnings]);
    }

    #[Route('/copy/execute', name: 'copy_execute', methods: ['POST'])]
    public function copyExecute(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        try {
            $payload = json_decode($req->getContent() ?: '{}', true);

            $sourceCourseId = (string) ($payload['sourceCourseId'] ?? '');
            $copyOption = (string) ($payload['copyOption'] ?? 'full_copy');
            $sameFileNameOption = (int) ($payload['sameFileNameOption'] ?? 2);
            $selectedResourcesMap = (array) ($payload['resources'] ?? []);

            if ('' === $sourceCourseId) {
                return $this->json(['error' => 'Missing sourceCourseId'], 400);
            }

            $cb = new CourseBuilder('partial');
            $cb->set_tools_to_build([
                'documents',
                'forums',
                'tool_intro',
                'links',
                'quizzes',
                'quiz_questions',
                'assets',
                'surveys',
                'survey_questions',
                'announcement',
                'events',
                'course_descriptions',
                'glossary',
                'wiki',
                'thematic',
                'attendance',
                'works',
                'gradebook',
                'learnpath_category',
                'learnpaths',
            ]);
            $legacyCourse = $cb->build(0, $sourceCourseId);

            if ('select_items' === $copyOption) {
                $legacyCourse = $this->filterLegacyCourseBySelection($legacyCourse, $selectedResourcesMap);

                if (empty($legacyCourse->resources) || !\is_array($legacyCourse->resources)) {
                    return $this->json(['error' => 'Selection produced no resources to copy'], 400);
                }
            }

            error_log('$legacyCourse :::: '.print_r($legacyCourse, true));

Are you sure print_r($legacyCourse, true) of type string|true can be used in concatenation?

            $restorer = new CourseRestorer($legacyCourse);
            $restorer->set_file_option($this->mapSameNameOption($sameFileNameOption));
            if (method_exists($restorer, 'setDebug')) {
                $restorer->setDebug($this->debug);
            }
            $restorer->restore();

            $dest = api_get_course_info();
            $redirectUrl = \sprintf('/course/%d/home', (int) $dest['real_id']);

            return $this->json([
                'ok' => true,
                'message' => 'Copy finished',
                'redirectUrl' => $redirectUrl,
            ]);
        } catch (Throwable $e) {
            return $this->json([
                'error' => 'Copy failed: '.$e->getMessage(),
                'details' => method_exists($e, 'getTraceAsString') ? $e->getTraceAsString() : null,
            ], 500);
        }
    }

    #[Route('/recycle/options', name: 'recycle_options', methods: ['GET'])]
    public function recycleOptions(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        // current course only
        $defaults = [
            'recycleOption' => 'select_items', // 'full_recycle' | 'select_items'
            'confirmNeeded' => true,           // show code-confirm input when full
        ];

        return $this->json(['defaults' => $defaults]);
    }

    #[Route('/recycle/resources', name: 'recycle_resources', methods: ['GET'])]
    public function recycleResources(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        // Build legacy Course from CURRENT course (not “source”)
        $cb = new CourseBuilder();
        $cb->set_tools_to_build([
            'documents', 'forums', 'tool_intro', 'links', 'quizzes', 'quiz_questions', 'assets', 'surveys',
            'survey_questions', 'announcement', 'events', 'course_descriptions', 'glossary', 'wiki',
            'thematic', 'attendance', 'works', 'gradebook', 'learnpath_category', 'learnpaths',
        ]);
        $course = $cb->build(0, api_get_course_id());

        $tree = $this->buildResourceTreeForVue($course);
        $warnings = empty($tree) ? ['This course has no resources.'] : [];

        return $this->json(['tree' => $tree, 'warnings' => $warnings]);
    }

    #[Route('/recycle/execute', name: 'recycle_execute', methods: ['POST'])]
    public function recycleExecute(Request $req, EntityManagerInterface $em): JsonResponse
    {
        try {
            $p = json_decode($req->getContent() ?: '{}', true);
            $recycleOption = (string) ($p['recycleOption'] ?? 'select_items'); // 'full_recycle' | 'select_items'
            $resourcesMap = (array) ($p['resources'] ?? []);
            $confirmCode = (string) ($p['confirm'] ?? '');

            $type = 'full_recycle' === $recycleOption ? 'full_backup' : 'select_items';

            if ('full_backup' === $type) {
                if ($confirmCode !== api_get_course_id()) {
                    return $this->json(['error' => 'Course code confirmation mismatch'], 400);
                }
            } else {
                if (empty($resourcesMap)) {
                    return $this->json(['error' => 'No resources selected'], 400);
                }
            }

            $courseCode = api_get_course_id();
            $courseInfo = api_get_course_info($courseCode);
            $courseId = (int) ($courseInfo['real_id'] ?? 0);
            if ($courseId <= 0) {
                return $this->json(['error' => 'Invalid course id'], 400);
            }

            $recycler = new CourseRecycler(
                $em,
                $courseCode,
                $courseId
            );

            $recycler->recycle($type, $resourcesMap);

            return $this->json([
                'ok' => true,
                'message' => 'Recycle finished',
            ]);
        } catch (Throwable $e) {
            return $this->json([
                'error' => 'Recycle failed: '.$e->getMessage(),
            ], 500);
        }
    }

    #[Route('/delete', name: 'delete', methods: ['POST'])]
    public function deleteCourse(int $node, Request $req): JsonResponse
    {
        // Basic permission gate (adjust roles to your policy if needed)
        if (!$this->isGranted('ROLE_ADMIN') && !$this->isGranted('ROLE_TEACHER') && !$this->isGranted('ROLE_CURRENT_COURSE_TEACHER')) {
            return $this->json(['error' => 'You are not allowed to delete this course'], 403);
        }

        try {
            $payload = json_decode($req->getContent() ?: '{}', true);
            $confirm = trim((string) ($payload['confirm'] ?? ''));

            if ('' === $confirm) {
                return $this->json(['error' => 'Missing confirmation value'], 400);
            }

            // Current course
            $courseInfo = api_get_course_info();
            if (empty($courseInfo)) {
                return $this->json(['error' => 'Unable to resolve current course'], 400);
            }

            $officialCode = (string) ($courseInfo['official_code'] ?? '');
            $runtimeCode = (string) api_get_course_id();                 // often equals official code
            $sysCode = (string) ($courseInfo['sysCode'] ?? '');       // used by legacy delete

            if ('' === $sysCode) {
                return $this->json(['error' => 'Invalid course system code'], 400);
            }

            // Accept either official_code or api_get_course_id() as confirmation
            $matches = hash_equals($officialCode, $confirm) || hash_equals($runtimeCode, $confirm);
            if (!$matches) {
                return $this->json(['error' => 'Course code confirmation mismatch'], 400);
            }

            // Legacy delete (removes course data + unregisters members in this course)
            // Throws on failure or returns void
            CourseManager::delete_course($sysCode);

            // Best-effort cleanup of legacy course session flags
            try {
                $ses = $req->getSession();
                $ses?->remove('_cid');
                $ses?->remove('_real_cid');
            } catch (Throwable) {
                // swallow — not critical
            }

            // Decide where to send the user afterwards
            // You can use '/index.php' or a landing page
            $redirectUrl = '/index.php';

            return $this->json([
                'ok' => true,
                'message' => 'Course deleted successfully',
                'redirectUrl' => $redirectUrl,
            ]);
        } catch (Throwable $e) {
            return $this->json([
                'error' => 'Failed to delete course: '.$e->getMessage(),
                'details' => method_exists($e, 'getTraceAsString') ? $e->getTraceAsString() : null,
            ], 500);
        }
    }

    #[Route('/moodle/export/options', name: 'moodle_export_options', methods: ['GET'])]
    public function moodleExportOptions(int $node, Request $req, UserRepository $users): JsonResponse
    {
        $defaults = [
            'moodleVersion' => '4',
            'scope' => 'full',
            'admin' => $users->getDefaultAdminForExport(),
        ];

        $tools = [
            ['value' => 'documents', 'label' => 'Documents (files & root HTML pages)'],
            ['value' => 'links', 'label' => 'Links (URL)'],
            ['value' => 'forums', 'label' => 'Forums'],
            ['value' => 'quizzes', 'label' => 'Quizzes', 'implies' => ['quiz_questions']],
            ['value' => 'surveys', 'label' => 'Surveys', 'implies' => ['survey_questions']],
            ['value' => 'works', 'label' => 'Tasks'],
            ['value' => 'glossary', 'label' => 'Glossary'],
            ['value' => 'learnpaths', 'label' => 'Paths learning'],
            ['value' => 'tool_intro', 'label' => 'Course Introduction'],
            ['value' => 'course_description', 'label' => 'Course descriptions'],
            ['value' => 'attendance', 'label' => 'Attendance'],
            ['value' => 'announcement', 'label' => 'Announcements'],
            ['value' => 'events', 'label' => 'Calendar events'],
            ['value' => 'wiki', 'label' => 'Wiki'],
            ['value' => 'thematic', 'label' => 'Thematic'],
            ['value' => 'gradebook', 'label' => 'Gradebook'],
        ];

        $defaults['tools'] = array_column($tools, 'value');

        return $this->json([
            'versions' => [
                ['value' => '3', 'label' => 'Moodle 3.x'],
                ['value' => '4', 'label' => 'Moodle 4.x'],
            ],
            'tools' => $tools,
            'defaults' => $defaults,
        ]);
    }

    #[Route('/moodle/export/resources', name: 'moodle_export_resources', methods: ['GET'])]
    public function moodleExportResources(int $node, Request $req): JsonResponse
    {
        // Enable/disable debug from request
        $this->setDebugFromRequest($req);
        $this->logDebug('[moodleExportResources] start', ['node' => $node]);

        try {
            // Normalize incoming tools from query (?tools[]=documents&tools[]=links ...)
            $selectedTools = $this->normalizeSelectedTools($req->query->all('tools'));

            // Default toolset tailored for Moodle export picker:
            $defaultToolsForMoodle = [
                'documents', 'links', 'forums',
                'quizzes', 'quiz_questions',
                'surveys', 'survey_questions',
                'learnpaths', 'learnpath_category',
                'works', 'glossary',
                'tool_intro',
                'course_descriptions',
                'attendance',
                'announcement',
                'events',
                'wiki',
                'thematic',
                'gradebook',
            ];

            // Use client tools if provided; otherwise our Moodle-safe defaults
            $tools = !empty($selectedTools) ? $selectedTools : $defaultToolsForMoodle;

            // Policy for this endpoint:
            //  - Never show gradebook
            //  - Always include tool_intro in the picker (harmless if empty)
            //$tools = array_values(array_diff($tools, ['gradebook']));
            if (!in_array('tool_intro', $tools, true)) {
                $tools[] = 'tool_intro';
            }

            $this->logDebug('[moodleExportResources] tools to build', $tools);

            // Build legacy Course snapshot from CURRENT course (not from a source course)
            $cb = new CourseBuilder();
            $cb->set_tools_to_build($tools);
            $course = $cb->build(0, api_get_course_id());

            // Build the UI-friendly tree
            $tree = $this->buildResourceTreeForVue($course);

            // Basic warnings for the client
            $warnings = empty($tree) ? ['This course has no resources.'] : [];

            // Some compact debug about the resulting tree
            if ($this->debug) {
                $this->logDebug(
                    '[moodleExportResources] tree summary',
                    array_map(
                        fn ($g) => [
                            'type'     => $g['type'] ?? '',
                            'title'    => $g['title'] ?? '',
                            'items'    => isset($g['items']) ? \count((array) $g['items']) : null,
                            'children' => isset($g['children']) ? \count((array) $g['children']) : null,
                        ],
                        $tree
                    )
                );
            }

            return $this->json([
                'tree'     => $tree,
                'warnings' => $warnings,
            ]);
        } catch (\Throwable $e) {
            // Defensive error path
            $this->logDebug('[moodleExportResources] exception', [
                'message' => $e->getMessage(),
                'file'    => $e->getFile().':'.$e->getLine(),
            ]);

            return $this->json([
                'error'   => 'Failed to build resource tree for Moodle export.',
                'details' => $e->getMessage(),
            ], 500);
        }
    }

    #[Route('/moodle/export/execute', name: 'moodle_export_execute', methods: ['POST'])]
    public function moodleExportExecute(int $node, Request $req, UserRepository $users): JsonResponse|BinaryFileResponse
    {
        $this->setDebugFromRequest($req);

        $p = json_decode($req->getContent() ?: '{}', true) ?: [];
        $moodleVersion = (string) ($p['moodleVersion'] ?? '4');  // "3" | "4"
        $scope         = (string) ($p['scope'] ?? 'full');       // "full" | "selected"
        $adminId       = (int) ($p['adminId'] ?? 0);
        $adminLogin    = trim((string) ($p['adminLogin'] ?? ''));
        $adminEmail    = trim((string) ($p['adminEmail'] ?? ''));
        $selected      = is_array($p['resources'] ?? null) ? (array) $p['resources'] : [];
        $toolsInput    = is_array($p['tools'] ?? null) ? (array) $p['tools'] : [];

        if (!\in_array($moodleVersion, ['3', '4'], true)) {
            return $this->json(['error' => 'Unsupported Moodle version'], 400);
        }
        if ('selected' === $scope && empty($selected)) {
            return $this->json(['error' => 'No resources selected'], 400);
        }

        $defaultTools = [
            'documents', 'links', 'forums',
            'quizzes', 'quiz_questions',
            'surveys', 'survey_questions',
            'learnpaths', 'learnpath_category',
            'works', 'glossary',
            'course_descriptions',
            'attendance',
            'announcement',
            'events',
            'wiki',
            'thematic',
            'gradebook',
        ];

        $tools = $this->normalizeSelectedTools($toolsInput);

        // If scope=selected, merge inferred tools from selection
        if ('selected' === $scope) {
            $inferred = $this->inferToolsFromSelection($selected);
            $tools = $this->normalizeSelectedTools(array_merge($tools, $inferred));
        }

        // Remove unsupported tools
        $clientSentNoTools = empty($toolsInput);
        $useDefault = ($scope === 'full' && $clientSentNoTools);
        $toolsToBuild = $useDefault ? $defaultTools : $tools;

        // Ensure "tool_intro" is present (append only if missing)
        if (!in_array('tool_intro', $toolsToBuild, true)) {
            $toolsToBuild[] = 'tool_intro';
        }

        // Final dedupe/normalize
        $toolsToBuild = array_values(array_unique($toolsToBuild));

        $this->logDebug('[moodleExportExecute] course tools to build (final)', $toolsToBuild);

        if ($adminId <= 0 || $adminLogin === '' || $adminEmail === '') {
            $adm        = $users->getDefaultAdminForExport();
            $adminId    = $adminId > 0 ? $adminId : (int) ($adm['id'] ?? 1);
            $adminLogin = $adminLogin !== '' ? $adminLogin : (string) ($adm['username'] ?? 'admin');
            $adminEmail = $adminEmail !== '' ? $adminEmail : (string) ($adm['email'] ?? 'admin@example.com');
        }

        $courseId = api_get_course_id();
        if (empty($courseId)) {
            return $this->json(['error' => 'No active course context'], 400);
        }

        $cb = new CourseBuilder();
        $cb->set_tools_to_build($toolsToBuild);
        $course = $cb->build(0, $courseId);

        if ('selected' === $scope) {
            $course = $this->filterLegacyCourseBySelection($course, $selected);
            if (empty($course->resources) || !\is_array($course->resources)) {
                return $this->json(['error' => 'Selection produced no resources to export'], 400);
            }
        }

        try {
            // === Export to Moodle MBZ ===
            $selectionMode = ($scope === 'selected');
            $exporter = new MoodleExport($course, $selectionMode);
            $exporter->setAdminUserData($adminId, $adminLogin, $adminEmail);

            $exportDir  = 'moodle_export_' . date('Ymd_His');
            $versionNum = ($moodleVersion === '3') ? 3 : 4;

            $this->logDebug('[moodleExportExecute] starting exporter', [
                'courseId'    => $courseId,
                'exportDir'   => $exportDir,
                'versionNum'  => $versionNum,
                'selection'   => $selectionMode,
                'scope'       => $scope,
            ]);

            $mbzPath = $exporter->export($courseId, $exportDir, $versionNum);

            if (!\is_string($mbzPath) || $mbzPath === '' || !is_file($mbzPath)) {
                return $this->json(['error' => 'Moodle export failed: artifact not found'], 500);
            }

            // Build download response
            $resp = new BinaryFileResponse($mbzPath);
            $resp->setContentDisposition(
                ResponseHeaderBag::DISPOSITION_ATTACHMENT,
                basename($mbzPath)
            );
            $resp->headers->set('X-Moodle-Version', (string) $versionNum);
            $resp->headers->set('X-Export-Scope', $scope);
            $resp->headers->set('X-Selection-Mode', $selectionMode ? '1' : '0');

            return $resp;
        } catch (\Throwable $e) {
            $this->logDebug('[moodleExportExecute] exception', [
                'message' => $e->getMessage(),
                'code'    => (int) $e->getCode(),
            ]);

            return $this->json(['error' => 'Moodle export failed: ' . $e->getMessage()], 500);
        }
    }

    /**
     * Normalize tool list to supported ones and add implied dependencies.
     *
     * @param array<int,string>|null $tools
     * @return string[]
     */
    private function normalizeSelectedTools(?array $tools): array
    {
        // Single list of supported tool buckets (must match CourseBuilder/exporters)
        $all = [
            'documents','links','quizzes','quiz_questions','surveys','survey_questions',
            'announcement','events','course_descriptions','glossary','wiki','thematic',
            'attendance','works','gradebook','learnpath_category','learnpaths','tool_intro','forums',
        ];

        // Implied dependencies
        $deps = [
            'quizzes'    => ['quiz_questions'],
            'surveys'    => ['survey_questions'],
            'learnpaths' => ['learnpath_category'],
        ];

        $sel = is_array($tools) ? array_values(array_intersect($tools, $all)) : [];

        foreach ($sel as $t) {
            foreach ($deps[$t] ?? [] as $d) {
                $sel[] = $d;
            }
        }

        // Unique and preserve a sane order based on $all
        $sel = array_values(array_unique($sel));
        usort($sel, static function ($a, $b) use ($all) {
            return array_search($a, $all, true) <=> array_search($b, $all, true);
        });

        return $sel;
    }

    #[Route('/cc13/export/options', name: 'cc13_export_options', methods: ['GET'])]
    public function cc13ExportOptions(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        return $this->json([
            'defaults' => ['scope' => 'full'],
            'supportedTypes' => Cc13Capabilities::exportableTypes(), // ['document','link','forum']
            'message' => 'Common Cartridge 1.3: documents (webcontent) and links (HTML stub as webcontent). Forums not exported yet.',
        ]);
    }

    #[Route('/cc13/export/resources', name: 'cc13_export_resources', methods: ['GET'])]
    public function cc13ExportResources(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        $cb = new CourseBuilder();
        $cb->set_tools_to_build(['documents', 'links', 'forums']);
        $course = $cb->build(0, api_get_course_id());

        $treeAll = $this->buildResourceTreeForVue($course);
        $tree    = Cc13Capabilities::filterTree($treeAll);

        // Count exportables using "items"
        $exportableCount = 0;
        foreach ($tree as $group) {
            if (empty($group['items']) || !\is_array($group['items'])) { continue; }

            if (($group['type'] ?? '') === 'forum') {
                foreach ($group['items'] as $cat) {
                    foreach (($cat['items'] ?? []) as $forumNode) {
                        if (($forumNode['type'] ?? '') === 'forum') { $exportableCount++; }
                    }
                }
            } else {
                $exportableCount += \count($group['items'] ?? []);
            }
        }

        $warnings = [];
        if ($exportableCount === 0) {
            $warnings[] = 'This course has no CC 1.3 exportable resources (documents, links or forums).';
        }

        return $this->json([
            'supportedTypes' => Cc13Capabilities::exportableTypes(), // ['document','link','forum']
            'tree'           => $tree,
            'preview'        => ['counts' => ['total' => $exportableCount]],
            'warnings'       => $warnings,
        ]);
    }

    #[Route('/cc13/export/execute', name: 'cc13_export_execute', methods: ['POST'])]
    public function cc13ExportExecute(int $node, Request $req): JsonResponse
    {
        $payload  = json_decode((string) $req->getContent(), true) ?: [];
        // If the client sent "resources", treat as selected even if scope says "full".
        $scope    = (string) ($payload['scope'] ?? (!empty($payload['resources']) ? 'selected' : 'full'));
        $selected = (array)  ($payload['resources'] ?? []);

        // Normalize selection structure (documents/links/forums/…)
        $normSel = Cc13Capabilities::filterSelection($selected);

        // Builder setup
        $tools = ['documents', 'links', 'forums'];
        $cb    = new CourseBuilder();

        $selectionMode = false;

        try {
            if ($scope === 'selected') {
                // Build a full snapshot first to expand any category-only selections.
                $cbFull = new CourseBuilder();
                $cbFull->set_tools_to_build($tools);
                $courseFull = $cbFull->build(0, api_get_course_id());

                $expanded = $this->expandCc13SelectionFromCategories($courseFull, $normSel);

                // Build per-tool ID map for CourseBuilder
                $map = [];
                if (!empty($expanded['documents'])) { $map['documents'] = array_map('intval', array_keys($expanded['documents'])); }
                if (!empty($expanded['links']))     { $map['links']     = array_map('intval', array_keys($expanded['links'])); }
                if (!empty($expanded['forums']))    { $map['forums']    = array_map('intval', array_keys($expanded['forums'])); }

                if (empty($map)) {
                    return $this->json(['error' => 'Please select at least one resource.'], 400);
                }

                $cb->set_tools_to_build($tools);
                $cb->set_tools_specific_id_list($map);
                $selectionMode = true;
            } else {
                $cb->set_tools_to_build($tools);
            }

            $course = $cb->build(0, api_get_course_id());

            // Safety net: if selection mode, ensure resources are filtered
            if ($selectionMode) {
                // Convert to the expected structure for filterCourseResources()
                $safeSelected = [
                    'documents' => array_fill_keys(array_map('intval', array_keys($normSel['documents'] ?? [])), true),
                    'links'     => array_fill_keys(array_map('intval', array_keys($normSel['links'] ?? [])), true),
                    'forums'    => array_fill_keys(array_map('intval', array_keys($normSel['forums'] ?? [])), true),
                ];
                // Also include expansions from categories
                $fullSnapshot = isset($courseFull) ? $courseFull : $course;
                $expandedAll  = $this->expandCc13SelectionFromCategories($fullSnapshot, $normSel);
                foreach (['documents','links','forums'] as $k) {
                    foreach (array_keys($expandedAll[$k] ?? []) as $idStr) {
                        $safeSelected[$k][(int)$idStr] = true;
                    }
                }

                $this->filterCourseResources($course, $safeSelected);
                if (empty($course->resources) || !\is_array($course->resources)) {
                    return $this->json(['error' => 'Nothing to export after filtering your selection.'], 400);
                }
            }

            $exporter  = new Cc13Export($course, $selectionMode, /*debug*/ false);
            $imsccPath = $exporter->export(api_get_course_id());
            $fileName  = basename($imsccPath);

            $downloadUrl = $this->generateUrl(
                    'cm_cc13_export_download',
                    ['node' => $node],
                    UrlGeneratorInterface::ABSOLUTE_URL
                ).'?file='.rawurlencode($fileName);

            return $this->json([
                'ok'          => true,
                'file'        => $fileName,
                'downloadUrl' => $downloadUrl,
                'message'     => 'Export finished.',
            ]);
        } catch (RuntimeException $e) {
            if (stripos($e->getMessage(), 'Nothing to export') !== false) {
                return $this->json(['error' => 'Nothing to export (no compatible resources found).'], 400);
            }
            return $this->json(['error' => 'CC 1.3 export failed: '.$e->getMessage()], 500);
        }
    }

    #[Route('/cc13/export/download', name: 'cc13_export_download', methods: ['GET'])]
    public function cc13ExportDownload(int $node, Request $req): BinaryFileResponse|JsonResponse
    {
        // Validate the filename we will serve
        $file = basename((string) $req->query->get('file', ''));
        // Example pattern: ABC123_cc13_20251017_195455.imscc
        if ($file === '' || !preg_match('/^[A-Za-z0-9_-]+_cc13_\d{8}_\d{6}\.imscc$/', $file)) {
            return $this->json(['error' => 'Invalid file'], 400);
        }

        $abs = rtrim(sys_get_temp_dir(), DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . $file;
        if (!is_file($abs)) {
            return $this->json(['error' => 'File not found'], 404);
        }

        // Stream file to the browser
        $resp = new BinaryFileResponse($abs);
        $resp->setContentDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, $file);
        $resp->headers->set('Content-Type', 'application/vnd.ims.ccv1p3+imscc');

        return $resp;
    }

    #[Route('/cc13/import', name: 'cc13_import', methods: ['POST'])]
    public function cc13Import(int $node, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);

        try {
            $file = $req->files->get('file');
            if (!$file || !$file->isValid()) {
                return $this->json(['error' => 'Missing or invalid upload.'], 400);
            }

            $ext = strtolower(pathinfo($file->getClientOriginalName() ?? '', PATHINFO_EXTENSION));
            if (!in_array($ext, ['imscc', 'zip'], true)) {
                return $this->json(['error' => 'Unsupported file type. Please upload .imscc or .zip'], 415);
            }

            // Move to a temp file
            $tmpZip = rtrim(sys_get_temp_dir(), DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR.
                'cc13_'.date('Ymd_His').'_'.bin2hex(random_bytes(3)).'.'.$ext;
            $file->move(dirname($tmpZip), basename($tmpZip));

            // Extract
            $extractDir = Imscc13Import::unzip($tmpZip);

            // Detect and validate format
            $format = Imscc13Import::detectFormat($extractDir);
            if ($format !== Imscc13Import::FORMAT_IMSCC13) {
                Imscc13Import::rrmdir($extractDir);
                @unlink($tmpZip);

It seems like you do not handle an error condition for unlink(). This can introduce security issues, and is generally not recommended.

                return $this->json(['error' => 'This package is not a Common Cartridge 1.3.'], 400);
            }

            // Execute import (creates Chamilo resources)
            $importer = new Imscc13Import();
            $importer->execute($extractDir);

            // Cleanup
            Imscc13Import::rrmdir($extractDir);
            @unlink($tmpZip);

            return $this->json([
                'ok' => true,
                'message' => 'CC 1.3 import completed successfully.',
            ]);
        } catch (\Throwable $e) {
            return $this->json([
                'error' => 'CC 1.3 import failed: '.$e->getMessage(),
            ], 500);
        }
    }

    #[Route(
        '/import/{backupId}/diagnose',
        name: 'import_diagnose',
        requirements: ['backupId' => '.+'],
        methods: ['GET']
    )]
    public function importDiagnose(int $node, string $backupId, Request $req): JsonResponse
    {
        $this->setDebugFromRequest($req);
        $this->logDebug('[importDiagnose] begin', ['node' => $node, 'backupId' => $backupId]);

        try {
            // Resolve absolute path of the uploaded/selected backup
            $path = $this->resolveBackupPath($backupId);
            if (!is_file($path)) {
                return $this->json(['error' => 'Backup file not found', 'path' => $path], 404);
            }

            // Read course_info.dat bytes from ZIP
            $ci = $this->readCourseInfoFromZip($path);
            if (empty($ci['ok'])) {
                $this->logDebug('[importDiagnose] course_info.dat not found or unreadable', $ci);

                return $this->json([
                    'meta' => [
                        'backupId' => $backupId,
                        'path'     => $path,
                    ],
                    'zip' => [
                        'error'           => $ci['error'] ?? 'unknown error',
                        'zip_list_sample' => $ci['zip_list_sample'] ?? [],
                        'num_files'       => $ci['num_files'] ?? null,
                    ],
                ], 200);
            }

            $raw  = (string) $ci['data'];
            $size = (int) ($ci['size'] ?? strlen($raw));
            $md5  = md5($raw);

            // Detect & decode content
            $probe = $this->decodeCourseInfo($raw);

            // Build a tiny scan snapshot
            $scan = [
                'has_graph'      => false,
                'resources_keys' => [],
                'note'           => 'No graph parsed',
            ];

            if (!empty($probe['is_serialized']) && isset($probe['value']) && \is_object($probe['value'])) {
                /** @var object $course */
                $course = $probe['value'];
                $scan['has_graph'] = true;
                $scan['resources_keys'] = (isset($course->resources) && \is_array($course->resources))
                    ? array_keys($course->resources)
                    : [];
                $scan['note'] = 'Parsed PHP serialized graph';
            } elseif (!empty($probe['is_json']) && \is_array($probe['json_preview'])) {
                $jp = $probe['json_preview'];
                $scan['has_graph'] = true;
                $scan['resources_keys'] = (isset($jp['resources']) && \is_array($jp['resources']))
                    ? array_keys($jp['resources'])
                    : [];
                $scan['note'] = 'Parsed JSON document';
            }

            $probeOut = $probe;
            unset($probeOut['value'], $probeOut['decoded']);

            $out = [
                'meta' => [
                    'backupId' => $backupId,
                    'path'     => $path,
                    'node'     => $node,
                ],
                'zip' => [
                    'name'  => $ci['name'] ?? null,
                    'index' => $ci['index'] ?? null,
                ],
                'course_info_dat' => [
                    'size_bytes' => $size,
                    'md5'        => $md5,
                ],
                'probe' => $probeOut,
                'scan'  => $scan,
            ];

            $this->logDebug('[importDiagnose] done', [
                'encoding'       => $probeOut['encoding'] ?? null,
                'has_graph'      => $scan['has_graph'],
                'resources_keys' => $scan['resources_keys'],
            ]);

            return $this->json($out);
        } catch (\Throwable $e) {
            $this->logDebug('[importDiagnose] exception', ['message' => $e->getMessage()]);

            return $this->json([
                'error' => 'Diagnosis failed: '.$e->getMessage(),
            ], 500);
        }
    }

    /**
     * Try to detect and decode course_info.dat content.
     * Hardened: preprocess typed-prop numeric strings and register legacy aliases
     * before attempting unserialize. Falls back to relaxed mode to avoid typed
     * property crashes during diagnosis.
     */
    private function decodeCourseInfo(string $raw): array
    {
        $r = [
            'encoding'      => 'raw',
            'decoded_len'   => strlen($raw),
            'magic_hex'     => bin2hex(substr($raw, 0, 8)),
            'magic_ascii'   => preg_replace('/[^\x20-\x7E]/', '.', substr($raw, 0, 16)),
            'steps'         => [],
            'decoded'       => null,
            'is_serialized' => false,
            'is_json'       => false,
            'json_preview'  => null,
        ];

        $isJson = static function (string $s): bool {
            $t = ltrim($s);
            return $t !== '' && ($t[0] === '{' || $t[0] === '[');
        };

        // Centralized tolerant unserialize with typed-props preprocessing
        $tryUnserializeTolerant = function (string $s, string $label) use (&$r) {
            $ok = false; $val = null; $err = null; $relaxed = false;

            // Ensure legacy aliases and coerce numeric strings before unserialize
            try {
                CourseArchiver::ensureLegacyAliases();
            } catch (\Throwable) { /* ignore */ }

            try {
                $s = CourseArchiver::preprocessSerializedPayloadForTypedProps($s);
            } catch (\Throwable) { /* ignore */ }

            // Strict mode
            set_error_handler(static function(){});
            try {
                $val = @unserialize($s, ['allowed_classes' => true]);
                $ok  = ($val !== false) || (trim($s) === 'b:0;');
            } catch (\Throwable $e) {
                $err = $e->getMessage();
                $ok  = false;
            } finally {
                restore_error_handler();
            }
            $r['steps'][] = ['action' => "unserialize[$label][strict]", 'ok' => $ok, 'error' => $err];

            // Relaxed fallback (no class instantiation) + deincomplete to stdClass
            if (!$ok) {
                $err2 = null;
                set_error_handler(static function(){});
                try {
                    $tmp = @unserialize($s, ['allowed_classes' => false]);
                    if ($tmp !== false || trim($s) === 'b:0;') {
                        $val = $this->deincomplete($tmp);
                        $ok  = true;
                        $relaxed = true;
                        $err = null;
                    }
                } catch (\Throwable $e2) {
                    $err2 = $e2->getMessage();
                } finally {
                    restore_error_handler();
                }
                $r['steps'][] = ['action' => "unserialize[$label][relaxed]", 'ok' => $ok, 'error' => $err2];
            }

            if ($ok) {
                $r['is_serialized'] = true;
                $r['decoded'] = null; // keep payload minimal
                $r['used_relaxed'] = $relaxed;
                return $val;
            }
            return null;
        };

        // 0) JSON as-is?
        if ($isJson($raw)) {
            $r['encoding'] = 'json';
            $r['is_json']  = true;
            $r['json_preview'] = json_decode($raw, true, 512, JSON_PARTIAL_OUTPUT_ON_ERROR);

            return $r;
        }

        // Direct PHP serialize (strict then relaxed, after preprocessing)
        if (($u = $tryUnserializeTolerant($raw, 'raw')) !== null) {
            $r['encoding'] = 'php-serialize';
            return $r + ['value' => $u];
        }

        // GZIP
        if (strncmp($raw, "\x1F\x8B", 2) === 0) {
            $dec = @gzdecode($raw);
            $r['steps'][] = ['action' => 'gzdecode', 'ok' => $dec !== false];
            if ($dec !== false) {
                if ($isJson($dec)) {
                    $r['encoding'] = 'gzip+json';
                    $r['is_json']  = true;
                    $r['json_preview'] = json_decode($dec, true, 512, JSON_PARTIAL_OUTPUT_ON_ERROR);
                    return $r;
                }
                if (($u = $tryUnserializeTolerant($dec, 'gzip')) !== null) {
                    $r['encoding'] = 'gzip+php-serialize';
                    return $r + ['value' => $u];
                }
            }
        }

        // ZLIB/DEFLATE
        $z2 = substr($raw, 0, 2);
        if ($z2 === "\x78\x9C" || $z2 === "\x78\xDA") {
            $dec = @gzuncompress($raw);
            $r['steps'][] = ['action' => 'gzuncompress', 'ok' => $dec !== false];
            if ($dec !== false) {
                if ($isJson($dec)) {
                    $r['encoding'] = 'zlib+json';
                    $r['is_json']  = true;
                    $r['json_preview'] = json_decode($dec, true, 512, JSON_PARTIAL_OUTPUT_ON_ERROR);
                    return $r;
                }
                if (($u = $tryUnserializeTolerant($dec, 'zlib')) !== null) {
                    $r['encoding'] = 'zlib+php-serialize';
                    return $r + ['value' => $u];
                }
            }
            $dec2 = @gzinflate($raw);
            $r['steps'][] = ['action' => 'gzinflate', 'ok' => $dec2 !== false];
            if ($dec2 !== false) {
                if ($isJson($dec2)) {
                    $r['encoding'] = 'deflate+json';
                    $r['is_json']  = true;
                    $r['json_preview'] = json_decode($dec2, true, 512, JSON_PARTIAL_OUTPUT_ON_ERROR);
                    return $r;
                }
                if (($u = $tryUnserializeTolerant($dec2, 'deflate')) !== null) {
                    $r['encoding'] = 'deflate+php-serialize';
                    return $r + ['value' => $u];
                }
            }
        }

        // BASE64 (e.g. "Tzo0ODoi..." -> base64('O:48:"Chamilo...'))
        if (preg_match('~^[A-Za-z0-9+/=\r\n]+$~', $raw)) {
            $dec = base64_decode($raw, true);
            $r['steps'][] = ['action' => 'base64_decode', 'ok' => $dec !== false];
            if ($dec !== false) {
                if ($isJson($dec)) {
                    $r['encoding'] = 'base64(json)';
                    $r['is_json']  = true;
                    $r['json_preview'] = json_decode($dec, true, 512, JSON_PARTIAL_OUTPUT_ON_ERROR);
                    return $r;
                }
                if (($u = $tryUnserializeTolerant($dec, 'base64')) !== null) {
                    $r['encoding'] = 'base64(php-serialize)';
                    return $r + ['value' => $u];
                }
                // base64 + gzip nested
                if (strncmp($dec, "\x1F\x8B", 2) === 0) {
                    $dec2 = @gzdecode($dec);
                    $r['steps'][] = ['action' => 'base64+gzdecode', 'ok' => $dec2 !== false];
                    if ($dec2 !== false && ($u = $tryUnserializeTolerant($dec2, 'base64+gzip')) !== null) {
                        $r['encoding'] = 'base64(gzip+php-serialize)';
                        return $r + ['value' => $u];
                    }
                }
            }
        }

        // Nested ZIP?
        if (strncmp($raw, "PK\x03\x04", 4) === 0) {
            $r['encoding'] = 'nested-zip';
        }

        return $r;
    }

    /**
     * Replace any __PHP_Incomplete_Class instances with stdClass (deep).
     * Also traverses arrays and objects (diagnostics-only).
     */
    private function deincomplete(mixed $v): mixed
    {
        if ($v instanceof \__PHP_Incomplete_Class) {
            $o = new \stdClass();
            foreach (get_object_vars($v) as $k => $vv) {
                $o->{$k} = $this->deincomplete($vv);
            }
            return $o;
        }
        if (is_array($v)) {
            foreach ($v as $k => $vv) {
                $v[$k] = $this->deincomplete($vv);
            }
            return $v;
        }
        if (is_object($v)) {
            foreach (get_object_vars($v) as $k => $vv) {
                $v->{$k} = $this->deincomplete($vv);
            }
            return $v;
        }
        return $v;
    }

    /**
     * Return [ok, name, index, size, data] for the first matching entry of course_info.dat (case-insensitive).
     * Also tries common subpaths, e.g., "course/course_info.dat".
     */
    private function readCourseInfoFromZip(string $zipPath): array
    {
        $candidates = [
            'course_info.dat',
            'course/course_info.dat',
            'backup/course_info.dat',
        ];

        $zip = new \ZipArchive();
        if (true !== ($err = $zip->open($zipPath))) {
            return ['ok' => false, 'error' => 'Failed to open ZIP (ZipArchive::open error '.$err.')'];
        }

        // First: direct name lookup (case-insensitive)
        $foundIdx = null;
        $foundName = null;

        for ($i = 0; $i < $zip->numFiles; $i++) {
            $st = $zip->statIndex($i);
            if (!$st || !isset($st['name'])) { continue; }

The expression $st of type array is implicitly converted to a boolean; are you sure this is intended? If so, consider using empty($expr) instead to make it clear that you intend to check for an array without elements.

            $name = (string) $st['name'];
            $base = strtolower(basename($name));
            if ($base === 'course_info.dat') {
                $foundIdx = $i;
                $foundName = $name;
                break;
            }
        }

        // Try specific candidate paths if direct scan failed
        if ($foundIdx === null) {
            foreach ($candidates as $cand) {
                $idx = $zip->locateName($cand, \ZipArchive::FL_NOCASE);
                if ($idx !== false) {
                    $foundIdx = $idx;
                    $foundName = $zip->getNameIndex($idx);
                    break;
                }
            }
        }

        if ($foundIdx === null) {
            // Build a short listing for debugging
            $list = [];
            $limit = min($zip->numFiles, 200);
            for ($i = 0; $i < $limit; $i++) {
                $n = $zip->getNameIndex($i);
                if ($n !== false) { $list[] = $n; }
            }
            $zip->close();

            return [
                'ok' => false,
                'error' => 'course_info.dat not found in archive',
                'zip_list_sample' => $list,
                'num_files' => $zip->numFiles,
            ];
        }

        $stat = $zip->statIndex($foundIdx);
        $size = (int) ($stat['size'] ?? 0);
        $fp   = $zip->getStream($foundName);
        if (!$fp) {

$fp is of type resource, thus it always evaluated to false.

            $zip->close();
            return ['ok' => false, 'error' => 'Failed to open stream for course_info.dat (getStream)'];
        }

        $data = stream_get_contents($fp);
        fclose($fp);
        $zip->close();

        if (!is_string($data)) {
            return ['ok' => false, 'error' => 'Failed to read course_info.dat contents'];
        }

        return [
            'ok'        => true,
            'name'      => $foundName,
            'index'     => $foundIdx,
            'size'      => $size,
            'data'      => $data,
        ];
    }

    /**
     * Build a Vue-friendly tree from legacy Course.
     */
    private function buildResourceTreeForVue(object $course): array
    {
        if ($this->debug) {
            $this->logDebug('[buildResourceTreeForVue] start');
        }

        $resources = \is_object($course) && isset($course->resources) && \is_array($course->resources)
            ? $course->resources
            : [];

        $legacyTitles = [];
        if (class_exists(CourseSelectForm::class) && method_exists(CourseSelectForm::class, 'getResourceTitleList')) {
            /** @var array<string,string> $legacyTitles */
            $legacyTitles = CourseSelectForm::getResourceTitleList();
        }
        $fallbackTitles = $this->getDefaultTypeTitles();
        $skipTypes = $this->getSkipTypeKeys();

        $tree = [];

        // Documents block
        if (!empty($resources['document']) && \is_array($resources['document'])) {
            $docs = $resources['document'];

            $normalize = function (string $rawPath, string $title, string $filetype): string {
                $p = trim($rawPath, '/');
                $p = (string) preg_replace('~^(?:document/)+~i', '', $p);
                $parts = array_values(array_filter(explode('/', $p), 'strlen'));

                // host
                if (!empty($parts) && ($parts[0] === 'localhost' || str_contains($parts[0], '.'))) {
                    array_shift($parts);
                }
                // course-code
                if (!empty($parts) && preg_match('~^[A-Z0-9_-]{6,}$~', $parts[0])) {
                    array_shift($parts);
                }

                $clean = implode('/', $parts);
                if ($clean === '' && $filetype !== 'folder') {
                    $clean = $title;
                }
                if ($filetype === 'folder') {
                    $clean = rtrim($clean, '/').'/';
                }
                return $clean;
            };

            $folderIdByPath = [];
            foreach ($docs as $obj) {
                if (!\is_object($obj)) { continue; }
                $ft = (string)($obj->filetype ?? $obj->file_type ?? '');
                if ($ft !== 'folder') { continue; }
                $rel = $normalize((string)$obj->path, (string)$obj->title, $ft);
                $key = rtrim($rel, '/');
                if ($key !== '') {
                    $folderIdByPath[strtolower($key)] = (int) $obj->source_id;
                }
            }

            $docRoot = [];
            $findChild = static function (array &$children, string $label): ?int {
                foreach ($children as $i => $n) {
                    if ((string)($n['label'] ?? '') === $label) { return $i; }
                }
                return null;
            };

            foreach ($docs as $obj) {
                if (!\is_object($obj)) { continue; }

                $title    = (string) $obj->title;
                $filetype = (string) ($obj->filetype ?? $obj->file_type ?? '');
                $rel      = $normalize((string) $obj->path, $title, $filetype);
                $parts    = array_values(array_filter(explode('/', trim($rel, '/')), 'strlen'));

                $cursor =& $docRoot;
                $soFar = '';
                $total = \count($parts);

                for ($i = 0; $i < $total; $i++) {
                    $seg      = $parts[$i];
                    $isLast   = ($i === $total - 1);
                    $isFolder = (!$isLast) || ($filetype === 'folder');

                    $soFar = ltrim($soFar.'/'.$seg, '/');
                    $label = $seg . ($isFolder ? '/' : '');

                    $idx = $findChild($cursor, $label);
                    if ($idx === null) {
                        if ($isFolder) {
                            $folderId = $folderIdByPath[strtolower($soFar)] ?? null;
                            $node = [
                                'id'         => $folderId ?? ('dir:'.$soFar),
                                'label'      => $label,
                                'selectable' => true,
                                'children'   => [],
                            ];
                        } else {
                            $node = [
                                'id'         => (int) $obj->source_id,
                                'label'      => $label,
                                'selectable' => true,
                            ];
                        }
                        $cursor[] = $node;
                        $idx = \count($cursor) - 1;
                    }

                    if ($isFolder) {
                        if (!isset($cursor[$idx]['children']) || !\is_array($cursor[$idx]['children'])) {
                            $cursor[$idx]['children'] = [];
                        }
                        $cursor =& $cursor[$idx]['children'];
                    }
                }
            }

            $sortTree = null;
            $sortTree = function (array &$nodes) use (&$sortTree) {
                usort($nodes, static fn($a, $b) => strcasecmp((string)$a['label'], (string)$b['label']));
                foreach ($nodes as &$n) {
                    if (isset($n['children']) && \is_array($n['children'])) {
                        $sortTree($n['children']);
                    }
                }
            };
            $sortTree($docRoot);

            $tree[] = [
                'type'     => 'document',
                'title'    => $legacyTitles['document'] ?? ($fallbackTitles['document'] ?? 'Documents'),
                'children' => $docRoot,
            ];

            $skipTypes['document'] = true;
        }

        // Forums block
        $hasForumData =
            (!empty($resources['forum']) || !empty($resources['Forum']))
            || (!empty($resources['forum_category']) || !empty($resources['Forum_Category']))
            || (!empty($resources['forum_topic']) || !empty($resources['ForumTopic']))
            || (!empty($resources['thread']) || !empty($resources['post']) || !empty($resources['forum_post']));

        if ($hasForumData) {
            $tree[] = $this->buildForumTreeForVue(
                $course,
                $legacyTitles['forum'] ?? ($fallbackTitles['forum'] ?? 'Forums')
            );
            $skipTypes['forum'] = true;
            $skipTypes['forum_category'] = true;
            $skipTypes['forum_topic'] = true;
            $skipTypes['forum_post'] = true;
            $skipTypes['thread'] = true;
            $skipTypes['post'] = true;
        }

        // Links block (Category → Link)
        $hasLinkData =
            (!empty($resources['link']) || !empty($resources['Link']))
            || (!empty($resources['link_category']) || !empty($resources['Link_Category']));

        if ($hasLinkData) {
            $tree[] = $this->buildLinkTreeForVue(
                $course,
                $legacyTitles['link'] ?? ($fallbackTitles['link'] ?? 'Links')
            );
            $skipTypes['link'] = true;
            $skipTypes['link_category'] = true;
        }

        foreach ($resources as $rawType => $items) {
            if (!\is_array($items) || empty($items)) {
                continue;
            }
            $typeKey = $this->normalizeTypeKey($rawType);
            if (isset($skipTypes[$typeKey])) {
                continue;
            }

            $groupTitle = $legacyTitles[$typeKey] ?? ($fallbackTitles[$typeKey] ?? ucfirst($typeKey));
            $group = [
                'type' => $typeKey,
                'title' => (string) $groupTitle,
                'items' => [],
            ];

            if ('gradebook' === $typeKey) {
                $group['items'][] = [
                    'id' => 'all',
                    'label' => 'Gradebook (all)',
                    'extra' => new stdClass(),
                    'selectable' => true,
                ];
                $tree[] = $group;
                continue;
            }

            foreach ($items as $id => $obj) {
                if (!\is_object($obj)) {
                    continue;
                }

                $idKey = is_numeric($id) ? (int) $id : (string) $id;
                if ((\is_int($idKey) && $idKey <= 0) || (\is_string($idKey) && '' === $idKey)) {
                    continue;
                }

                if (!$this->isSelectableItem($typeKey, $obj)) {
                    continue;
                }

                $label = $this->resolveItemLabel($typeKey, $obj, \is_int($idKey) ? $idKey : 0);

                if ('tool_intro' === $typeKey && '#0' === $label && \is_string($idKey)) {
                    $label = $idKey;
                }

                $extra = $this->buildExtra($typeKey, $obj);

                $group['items'][] = [
                    'id' => $idKey,
                    'label' => $label,
                    'extra' => $extra ?: new stdClass(),
                    'selectable' => true,
                ];
            }

            if (!empty($group['items'])) {
                usort(
                    $group['items'],
                    static fn ($a, $b) => strcasecmp((string) $a['label'], (string) $b['label'])
                );
                $tree[] = $group;
            }
        }

        // Preferred order
        $preferredOrder = [
            'announcement', 'document', 'course_description', 'learnpath', 'quiz', 'forum', 'glossary', 'link',
            'survey', 'thematic', 'work', 'attendance', 'wiki', 'calendar_event', 'events', 'tool_intro', 'gradebook',
        ];
        usort($tree, static function ($a, $b) use ($preferredOrder) {
            $ia = array_search($a['type'], $preferredOrder, true);
            $ib = array_search($b['type'], $preferredOrder, true);
            if (false !== $ia && false !== $ib) {
                return $ia <=> $ib;
            }
            if (false !== $ia) {
                return -1;
            }
            if (false !== $ib) {
                return 1;
            }

            return strcasecmp($a['title'], $b['title']);
        });

        if ($this->debug) {
            $this->logDebug(
                '[buildResourceTreeForVue] end groups',
                array_map(fn ($g) => ['type' => $g['type'], 'items' => \count($g['items'] ?? []), 'children' => \count($g['children'] ?? [])], $tree)
            );
        }

        return $tree;
    }


    /**
     * Build forum tree (Category → Forum → Topic) for the UI.
     * Uses only "items" (no "children") and sets UI hints (has_children, item_count).
     */
    private function buildForumTreeForVue(object $course, string $groupTitle): array
    {
        $this->logDebug('[buildForumTreeForVue] start');

        $res = \is_array($course->resources ?? null) ? $course->resources : [];

        // Buckets (defensive: accept legacy casings / aliases)
        $catRaw   = $res['forum_category'] ?? $res['Forum_Category'] ?? [];
        $forumRaw = $res['forum']          ?? $res['Forum']          ?? [];
        $topicRaw = $res['forum_topic']    ?? $res['ForumTopic']     ?? ($res['thread'] ?? []);
        $postRaw  = $res['forum_post']     ?? $res['Forum_Post']     ?? ($res['post'] ?? []);

        $this->logDebug('[buildForumTreeForVue] raw counts', [
            'categories' => \is_array($catRaw) ? \count($catRaw) : 0,
            'forums'     => \is_array($forumRaw) ? \count($forumRaw) : 0,
            'topics'     => \is_array($topicRaw) ? \count($topicRaw) : 0,
            'posts'      => \is_array($postRaw) ? \count($postRaw) : 0,
        ]);

        // Quick classifiers (defensive)
        $isForum = function (object $o): bool {
            $e = (isset($o->obj) && \is_object($o->obj)) ? $o->obj : $o;
            if (isset($e->forum_title) && \is_string($e->forum_title)) { return true; }
            if (isset($e->default_view) || isset($e->allow_anonymous)) { return true; }
            if ((isset($e->forum_category) || isset($e->forum_category_id) || isset($e->category_id)) && !isset($e->forum_id)) { return true; }
            return false;
        };
        $isTopic = function (object $o): bool {
            $e = (isset($o->obj) && \is_object($o->obj)) ? $o->obj : $o;
            if (isset($e->forum_id) && (isset($e->thread_title) || isset($e->thread_date) || isset($e->poster_name))) { return true; }
            if (isset($e->forum_id) && !isset($e->forum_title)) { return true; }
            return false;
        };
        $getForumCategoryId = function (object $forum): int {
            $e = (isset($forum->obj) && \is_object($forum->obj)) ? $forum->obj : $forum;
            $cid = (int) ($e->forum_category ?? 0);
            if ($cid <= 0) { $cid = (int) ($e->forum_category_id ?? 0); }
            if ($cid <= 0) { $cid = (int) ($e->category_id ?? 0); }
            return $cid;
        };

        // Build categories
        $cats = [];
        foreach ($catRaw as $id => $obj) {
            $id = (int) $id;
            if ($id <= 0 || !\is_object($obj)) { continue; }
            $label = $this->resolveItemLabel('forum_category', $this->objectEntity($obj), $id);
            $cats[$id] = [
                'id'         => $id,
                'type'       => 'forum_category',
                'label'      => ($label !== '' ? $label : 'Category #'.$id).'/',
                'selectable' => true,
                'items'      => [],
                'has_children' => false,
                'item_count'   => 0,
                'extra'      => ['filetype' => 'folder'],
            ];
        }
        // Virtual "Uncategorized"
        $uncatKey = -9999;
        if (!isset($cats[$uncatKey])) {
            $cats[$uncatKey] = [
                'id'           => $uncatKey,
                'type'         => 'forum_category',
                'label'        => 'Uncategorized/',
                'selectable'   => true,
                'items'        => [],
                '_virtual'     => true,
                'has_children' => false,
                'item_count'   => 0,
                'extra'        => ['filetype' => 'folder'],
            ];
        }

        // Forums
        $forums = [];
        foreach ($forumRaw as $id => $obj) {
            $id = (int) $id;
            if ($id <= 0 || !\is_object($obj)) { continue; }
            if (!$isForum($obj)) {
                $this->logDebug('[buildForumTreeForVue] skipped non-forum in forum bucket', ['id' => $id]);
                continue;
            }
            $forums[$id] = $this->objectEntity($obj);
        }

        // Topics (+ post counts)
        $topics = [];
        $postCountByTopic = [];
        foreach ($topicRaw as $id => $obj) {
            $id = (int) $id;
            if ($id <= 0 || !\is_object($obj)) { continue; }
            if ($isForum($obj) && !$isTopic($obj)) {
                $this->logDebug('[buildForumTreeForVue] WARNING: forum object found in topic bucket; skipping', ['id' => $id]);
                continue;
            }
            if (!$isTopic($obj)) { continue; }
            $topics[$id] = $this->objectEntity($obj);
        }
        foreach ($postRaw as $id => $obj) {
            $id = (int) $id;
            if ($id <= 0 || !\is_object($obj)) { continue; }
            $e = $this->objectEntity($obj);
            $tid = (int) ($e->thread_id ?? 0);
            if ($tid > 0) { $postCountByTopic[$tid] = ($postCountByTopic[$tid] ?? 0) + 1; }
        }

        // Attach topics to forums and forums to categories
        foreach ($forums as $fid => $f) {
            $catId = $getForumCategoryId($f);
            if (!isset($cats[$catId])) { $catId = $uncatKey; }

            $forumNode = [
                'id'         => $fid,
                'type'       => 'forum',
                'label'      => $this->resolveItemLabel('forum', $f, $fid),
                'extra'      => $this->buildExtra('forum', $f) ?: new \stdClass(),
                'selectable' => true,
                'items'      => [],
                // UI hints
                'has_children' => false,
                'item_count'   => 0,
                'ui_depth'     => 2,
            ];

            foreach ($topics as $tid => $t) {
                if ((int) ($t->forum_id ?? 0) !== $fid) { continue; }

                $author  = (string) ($t->thread_poster_name ?? $t->poster_name ?? '');
                $date    = (string) ($t->thread_date ?? '');
                $nPosts  = (int) ($postCountByTopic[$tid] ?? 0);

                $topicLabel = $this->resolveItemLabel('forum_topic', $t, $tid);
                $meta = [];
                if ($author !== '') { $meta[] = $author; }
                if ($date   !== '') { $meta[] = $date; }
                if ($meta) { $topicLabel .= ' ('.implode(', ', $meta).')'; }
                if ($nPosts > 0) { $topicLabel .= ' — '.$nPosts.' post'.(1 === $nPosts ? '' : 's'); }

                $forumNode['items'][] = [
                    'id'         => $tid,
                    'type'       => 'forum_topic',
                    'label'      => $topicLabel,
                    'extra'      => new \stdClass(),
                    'selectable' => true,
                    'ui_depth'   => 3,
                    'item_count' => 0,
                ];
            }

            if (!empty($forumNode['items'])) {
                usort($forumNode['items'], static fn ($a, $b) => strcasecmp((string) $a['label'], (string) $b['label']));
                $forumNode['has_children'] = true;
                $forumNode['item_count']   = \count($forumNode['items']);
            }

            $cats[$catId]['items'][] = $forumNode;
        }

        // Remove empty virtual category; sort forums inside each category
        $catNodes = array_values(array_filter($cats, static function ($c) {
            if (!empty($c['_virtual']) && empty($c['items'])) { return false; }
            return true;
        }));

        // Flatten stray forums (defensive) and finalize UI hints
        foreach ($catNodes as &$cat) {
            if (!empty($cat['items'])) {
                $lift = [];
                foreach ($cat['items'] as &$forumNode) {
                    if (($forumNode['type'] ?? '') !== 'forum' || empty($forumNode['items'])) { continue; }
                    $keep = [];
                    foreach ($forumNode['items'] as $child) {
                        if (($child['type'] ?? '') === 'forum') {
                            $lift[] = $child;
                            $this->logDebug('[buildForumTreeForVue] flatten: lifted nested forum', [
                                'parent_forum_id' => $forumNode['id'] ?? null,
                                'lifted_forum_id' => $child['id'] ?? null,
                                'cat_id'          => $cat['id'] ?? null,
                            ]);
                        } else {
                            $keep[] = $child;
                        }
                    }
                    $forumNode['items']        = $keep;
                    $forumNode['has_children'] = !empty($keep);
                    $forumNode['item_count']   = \count($keep);
                }
                unset($forumNode);

                foreach ($lift as $n) { $cat['items'][] = $n; }
                usort($cat['items'], static fn ($a, $b) => strcasecmp((string) $a['label'], (string) $b['label']));
            }

            // UI hints for category
            $cat['has_children'] = !empty($cat['items']);
            $cat['item_count']   = \count($cat['items'] ?? []);
        }
        unset($cat);

        $this->logDebug('[buildForumTreeForVue] end', ['categories' => \count($catNodes)]);

        return [
            'type'  => 'forum',
            'title' => $groupTitle,
            'items' => $catNodes,
        ];
    }

    /**
     * Canonicalizes a resource/bucket key used anywhere in the flow (UI type, snapshot key, etc.)
     * Keep this small and stable; only map well-known aliases to the canonical snapshot keys we expect.
     */
    private function normalizeTypeKey(string $key): string
    {
        $k = strtolower(trim($key));

        // Documents
        if (in_array($k, ['document','documents'], true)) {
            return 'document';
        }

        // Links
        if (in_array($k, ['link','links'], true)) {
            return 'link';
        }
        if (in_array($k, ['link_category','linkcategory','link_categories'], true)) {
            return 'link_category';
        }

        // Forums
        if ($k === 'forum_category' || $k === 'forumcategory') {
            return 'Forum_Category';
        }
        if ($k === 'forums') {
            return 'forum';
        }

        // Announcements / News
        if (in_array($k, ['announcement','announcements','news'], true)) {
            return 'announcement';
        }

        // Attendance
        if (in_array($k, ['attendance','attendances'], true)) {
            return 'attendance';
        }

        // Course descriptions
        if (in_array($k, ['course_description','course_descriptions','description','descriptions'], true)) {
            return 'course_descriptions';
        }

        // Events / Calendar
        if (in_array($k, ['event','events','calendar','calendar_event','calendar_events'], true)) {
            return 'events';
        }

        // Learnpaths
        if ($k === 'learnpaths') {
            return 'learnpath';
        }

        // Quizzes
        if (in_array($k, ['quiz','quizzes'], true)) {
            return 'quiz';
        }

        // Default: return as-is
        return $k;
    }

    /**
     * Keys to skip as top-level groups in UI.
     *
     * @return array<string,bool>
     */
    private function getSkipTypeKeys(): array
    {
        return [
            'forum_category' => true,
            'forum_topic' => true,
            'forum_post' => true,
            'thread' => true,
            'post' => true,
            'exercise_question' => true,
            'survey_question' => true,
            'survey_invitation' => true,
            'session_course' => true,
            'scorm' => true,
            'asset' => true,
            'link_category' => true,
        ];
    }

    /**
     * Default labels for groups.
     *
     * @return array<string,string>
     */
    private function getDefaultTypeTitles(): array
    {
        return [
            'announcement' => 'announcement',
            'document' => 'Documents',
            'glossary' => 'Glossaries',
            'calendar_event' => 'Calendar events',
            'event' => 'Calendar events',
            'events' => 'Calendar events',
            'link' => 'Links',
            'course_description' => 'Course descriptions',
            'learnpath' => 'Parcours',
            'learnpath_category' => 'Learning path categories',
            'forum' => 'Forums',
            'forum_category' => 'Forum categories',
            'quiz' => 'Exercices',
            'test_category' => 'Test categories',
            'wiki' => 'Wikis',
            'thematic' => 'Thematics',
            'attendance' => 'Attendances',
            'work' => 'Works',
            'session_course' => 'Session courses',
            'gradebook' => 'Gradebook',
            'scorm' => 'SCORM packages',
            'survey' => 'Surveys',
            'survey_question' => 'Survey questions',
            'survey_invitation' => 'Survey invitations',
            'asset' => 'Assets',
            'tool_intro' => 'Tool introductions',
        ];
    }

    /**
     * Decide if an item is selectable (UI).
     */
    private function isSelectableItem(string $type, object $obj): bool
    {
        if ($type === 'announcement') {
            // Require at least a non-empty title
            return isset($obj->title) && trim((string)$obj->title) !== '';
        }

        if ('document' === $type) {
            return true;
        }

        return true;
    }

    /**
     * Resolve label for an item with fallbacks.
     */
    private function resolveItemLabel(string $type, object $obj, int $fallbackId): string
    {
        if ($type === 'announcement') {
            return (string)($obj->title ?? ("Announcement #".$obj->iid));
        }

        $entity = $this->objectEntity($obj);

        foreach (['title', 'name', 'subject', 'question', 'display', 'code', 'description'] as $k) {
            if (isset($entity->{$k}) && \is_string($entity->{$k}) && '' !== trim($entity->{$k})) {
                return trim((string) $entity->{$k});
            }
        }

        if (isset($obj->params) && \is_array($obj->params)) {
            foreach (['title', 'name', 'subject', 'display', 'description'] as $k) {
                if (!empty($obj->params[$k]) && \is_string($obj->params[$k])) {
                    return $obj->params[$k];
                }
            }
        }

        switch ($type) {
            case 'events':
                $title = trim((string)($entity->title ?? $entity->name ?? $entity->subject ?? ''));
                if ($title !== '') { return $title; }

                return '#'.$fallbackId;
            case 'document':
                $raw = (string) ($entity->path ?? $obj->path ?? '');
                if ('' !== $raw) {
                    $rel = ltrim($raw, '/');
                    $rel = preg_replace('~^document/?~', '', $rel);
                    $fileType = (string) ($entity->file_type ?? $obj->file_type ?? '');
                    if ('folder' === $fileType) {
                        $rel = rtrim($rel, '/').'/';
                    }

                    return '' !== $rel ? $rel : basename($raw);
                }

                if (!empty($obj->title)) {
                    return (string) $obj->title;
                }

                break;

            case 'course_description':
                if (!empty($obj->title)) {
                    return (string) $obj->title;
                }
                $t = (int) ($obj->description_type ?? 0);
                $names = [
                    1 => 'Description',
                    2 => 'Objectives',
                    3 => 'Topics',
                    4 => 'Methodology',
                    5 => 'Course material',
                    6 => 'Resources',
                    7 => 'Assessment',
                    8 => 'Custom',
                ];

                return $names[$t] ?? ('#'.$fallbackId);

            case 'announcement':
                if (!empty($obj->title)) {
                    return (string) $obj->title;
                }

                break;

            case 'forum':
                if (!empty($entity->forum_title)) {
                    return (string) $entity->forum_title;
                }

                break;

            case 'forum_category':
                if (!empty($entity->cat_title)) {
                    return (string) $entity->cat_title;
                }

                break;

            case 'link':
                if (!empty($obj->title)) {
                    return (string) $obj->title;
                }
                if (!empty($obj->url)) {
                    return (string) $obj->url;
                }

                break;

            case 'survey':
                if (!empty($obj->title)) {
                    return trim((string) $obj->title);
                }

                break;

            case 'learnpath':
                if (!empty($obj->name)) {
                    return (string) $obj->name;
                }

                break;

            case 'thematic':
                if (isset($obj->params['title']) && \is_string($obj->params['title'])) {
                    return (string) $obj->params['title'];
                }

                break;

            case 'quiz':
                if (!empty($entity->title)) {
                    return (string) $entity->title;
                }

                break;

            case 'forum_topic':
                if (!empty($entity->thread_title)) {
                    return (string) $entity->thread_title;
                }

                break;
        }

        return '#'.$fallbackId;
    }

    /**
     * Extract wrapped entity (->obj) or the object itself.
     */
    private function objectEntity(object $resource): object
    {
        if (isset($resource->obj) && \is_object($resource->obj)) {
            return $resource->obj;
        }

        return $resource;
    }

    /**
     * Extra payload per item for UI (optional).
     */
    private function buildExtra(string $type, object $obj): array
    {
        $extra = [];

        $get = static function (object $o, string $k, $default = null) {
            return (isset($o->{$k}) && (\is_string($o->{$k}) || is_numeric($o->{$k}))) ? $o->{$k} : $default;
        };

        switch ($type) {
            case 'document':
                $extra['path'] = (string) ($get($obj, 'path', '') ?? '');
                $extra['filetype'] = (string) ($get($obj, 'file_type', '') ?? '');
                $extra['size'] = (string) ($get($obj, 'size', '') ?? '');

                break;

            case 'link':
                $extra['url'] = (string) ($get($obj, 'url', '') ?? '');
                $extra['target'] = (string) ($get($obj, 'target', '') ?? '');

                break;

            case 'forum':
                $entity = $this->objectEntity($obj);
                $extra['category_id'] = (string) ($entity->forum_category ?? '');
                $extra['default_view'] = (string) ($entity->default_view ?? '');

                break;

            case 'learnpath':
                $extra['name'] = (string) ($get($obj, 'name', '') ?? '');
                $extra['items'] = isset($obj->items) && \is_array($obj->items) ? array_map(static function ($i) {
                    return [
                        'id' => (int) ($i['id'] ?? 0),
                        'title' => (string) ($i['title'] ?? ''),
                        'type' => (string) ($i['item_type'] ?? ''),
                        'path' => (string) ($i['path'] ?? ''),
                    ];
                }, $obj->items) : [];

                break;

            case 'thematic':
                if (isset($obj->params) && \is_array($obj->params)) {
                    $extra['active'] = (string) ($obj->params['active'] ?? '');
                }

                break;

            case 'quiz':
                $entity = $this->objectEntity($obj);
                $extra['question_ids'] = isset($entity->question_ids) && \is_array($entity->question_ids)
                    ? array_map('intval', $entity->question_ids)
                    : [];

                break;

            case 'survey':
                $entity = $this->objectEntity($obj);
                $extra['question_ids'] = isset($entity->question_ids) && \is_array($entity->question_ids)
                    ? array_map('intval', $entity->question_ids)
                    : [];

                break;
            case 'events':
                $entity = $this->objectEntity($obj);
                $extra['start']    = (string)($entity->start ?? $entity->start_date ?? $entity->timestart ?? '');
                $extra['end']      = (string)($entity->end ?? $entity->end_date ?? $entity->timeend ?? '');
                $extra['all_day']  = (string)($entity->all_day ?? $entity->allday ?? '');
                $extra['location'] = (string)($entity->location ?? '');
                break;
        }

        return array_filter($extra, static fn ($v) => !('' === $v || null === $v || [] === $v));
    }

    /**
     * Get first existing key from candidates.
     */
    private function firstExistingKey(array $orig, array $candidates): ?string
    {
        foreach ($candidates as $k) {
            if (isset($orig[$k]) && \is_array($orig[$k]) && !empty($orig[$k])) {
                return $k;
            }
        }

        return null;
    }

    /**
     * Filter legacy Course by UI selections (and pull dependencies).
     *
     * @param array $selected [type => [id => true]]
     */
    private function filterLegacyCourseBySelection(object $course, array $selected): object
    {
        // Sanitize incoming selection (frontend sometimes sends synthetic groups)
        $selected = array_filter($selected, 'is_array');
        unset($selected['undefined']);

        $this->logDebug('[filterSelection] start', ['selected_types' => array_keys($selected)]);

        if (empty($course->resources) || !\is_array($course->resources)) {
            $this->logDebug('[filterSelection] course has no resources');

            return $course;
        }

        /** @var array<string,mixed> $orig */
        $orig = $course->resources;

        // Preserve meta buckets (keys that start with "__")
        $__metaBuckets = [];
        foreach ($orig as $k => $v) {
            if (\is_string($k) && str_starts_with($k, '__')) {
                $__metaBuckets[$k] = $v;
            }
        }

        $getBucket = fn (array $a, string $key): array => (isset($a[$key]) && \is_array($a[$key])) ? $a[$key] : [];

        // ---------- Forums flow ----------
        if (!empty($selected['forum'])) {
            $selForums = array_fill_keys(array_map('strval', array_keys($selected['forum'])), true);
            if (!empty($selForums)) {
                // tolerant lookups
                $forums  = $this->findBucket($orig, 'forum');
                $threads = $this->findBucket($orig, 'forum_topic');
                $posts   = $this->findBucket($orig, 'forum_post');

                $catsToKeep = [];

                foreach ($forums as $fid => $f) {
                    if (!isset($selForums[(string) $fid])) {
                        continue;
                    }
                    $e = (isset($f->obj) && \is_object($f->obj)) ? $f->obj : $f;
                    $cid = (int) ($e->forum_category ?? $e->forum_category_id ?? $e->category_id ?? 0);
                    if ($cid > 0) {
                        $catsToKeep[$cid] = true;
                    }
                }

                $threadToKeep = [];
                foreach ($threads as $tid => $t) {
                    $e = (isset($t->obj) && \is_object($t->obj)) ? $t->obj : $t;
                    if (isset($selForums[(string) ($e->forum_id ?? '')])) {
                        $threadToKeep[(int) $tid] = true;
                    }
                }

                $postToKeep = [];
                foreach ($posts as $pid => $p) {
                    $e = (isset($p->obj) && \is_object($p->obj)) ? $p->obj : $p;
                    if (isset($threadToKeep[(int) ($e->thread_id ?? 0)])) {
                        $postToKeep[(int) $pid] = true;
                    }
                }

                $out = [];
                foreach ($selected as $type => $ids) {
                    if (!\is_array($ids) || empty($ids)) {
                        continue;
                    }
                    $bucket = $this->findBucket($orig, (string) $type);
                    $key    = $this->findBucketKey($orig, (string) $type);
                    if ($key !== null && !empty($bucket)) {
                        $idsMap = array_fill_keys(array_map('strval', array_keys($ids)), true);
                        $out[$key] = $this->intersectBucketByIds($bucket, $idsMap);
                    }
                }

                $forumCat     = $this->findBucket($orig, 'forum_category');
                $forumBucket  = $this->findBucket($orig, 'forum');
                $threadBucket = $this->findBucket($orig, 'forum_topic');
                $postBucket   = $this->findBucket($orig, 'forum_post');

                if (!empty($forumCat) && !empty($catsToKeep)) {
                    $out[$this->findBucketKey($orig, 'forum_category') ?? 'Forum_Category'] =
                        array_intersect_key(
                            $forumCat,
                            array_fill_keys(array_map('strval', array_keys($catsToKeep)), true)
                        );
                }

                if (!empty($forumBucket)) {
                    $out[$this->findBucketKey($orig, 'forum') ?? 'forum'] =
                        array_intersect_key($forumBucket, $selForums);
                }
                if (!empty($threadBucket)) {
                    $out[$this->findBucketKey($orig, 'forum_topic') ?? 'thread'] =
                        array_intersect_key(
                            $threadBucket,
                            array_fill_keys(array_map('strval', array_keys($threadToKeep)), true)
                        );
                }
                if (!empty($postBucket)) {
                    $out[$this->findBucketKey($orig, 'forum_post') ?? 'post'] =
                        array_intersect_key(
                            $postBucket,
                            array_fill_keys(array_map('strval', array_keys($postToKeep)), true)
                        );
                }

                // If we have forums but no Forum_Category (edge), keep original categories
                if (!empty($out['forum']) && empty($out['Forum_Category']) && !empty($forumCat)) {
                    $out['Forum_Category'] = $forumCat;
                }

                $out = array_filter($out);
                $course->resources = !empty($__metaBuckets) ? ($__metaBuckets + $out) : $out;

                $this->logDebug('[filterSelection] end (forums)', [
                    'kept_types' => array_keys($course->resources),
                    'forum_counts' => [
                        'Forum_Category' => \is_array($course->resources['Forum_Category'] ?? null) ? \count($course->resources['Forum_Category']) : 0,
                        'forum'          => \is_array($course->resources['forum'] ?? null) ? \count($course->resources['forum']) : 0,
                        'thread'         => \is_array($course->resources['thread'] ?? null) ? \count($course->resources['thread']) : 0,
                        'post'           => \is_array($course->resources['post'] ?? null) ? \count($course->resources['post']) : 0,
                    ],
                ]);

                return $course;
            }
        }

        // ---------- Generic + quiz/survey/gradebook ----------
        $keep = [];
        foreach ($selected as $type => $ids) {
            if (!\is_array($ids) || empty($ids)) {
                continue;
            }
            $legacyKey = $this->findBucketKey($orig, (string) $type);
            if ($legacyKey === null) {
                continue;
            }
            $bucket = $orig[$legacyKey] ?? [];
            if (!empty($bucket) && \is_array($bucket)) {
                $idsMap = array_fill_keys(array_map('strval', array_keys($ids)), true);
                $keep[$legacyKey] = $this->intersectBucketByIds($bucket, $idsMap);
            }
        }

        // Gradebook
        $gbKey = $this->firstExistingKey($orig, ['gradebook', 'Gradebook', 'GradebookBackup', 'gradebookbackup']);
        if ($gbKey && !empty($selected['gradebook'])) {
            $gbBucket = $getBucket($orig, $gbKey);
            if (!empty($gbBucket)) {
                $selIds = array_keys(array_filter((array) $selected['gradebook']));
                $firstItem = reset($gbBucket);

                if (\in_array('all', $selIds, true) || !\is_object($firstItem)) {
                    $keep[$gbKey] = $gbBucket;
                    $this->logDebug('[filterSelection] kept full gradebook', ['key' => $gbKey, 'count' => \count($gbBucket)]);
                } else {
                    $keep[$gbKey] = array_intersect_key($gbBucket, array_fill_keys(array_map('strval', $selIds), true));
                    $this->logDebug('[filterSelection] kept partial gradebook', ['key' => $gbKey, 'count' => \count($keep[$gbKey])]);
                }
            }
        }

        // Quizzes -> questions (+ images)
        $quizKey = $this->firstExistingKey($orig, ['quiz','Quiz']);
        if ($quizKey && !empty($keep[$quizKey])) {
            $questionKey = $this->firstExistingKey($orig, ['Exercise_Question','exercise_question', \defined('RESOURCE_QUIZQUESTION') ? RESOURCE_QUIZQUESTION : '']);
            if ($questionKey) {
                $qids = [];
                foreach ($keep[$quizKey] as $qid => $qwrap) {
                    $q = (isset($qwrap->obj) && \is_object($qwrap->obj)) ? $qwrap->obj : $qwrap;
                    if (!empty($q->question_ids) && \is_array($q->question_ids)) {
                        foreach ($q->question_ids as $sid) {
                            $qids[(string) $sid] = true;
                        }
                    }
                }
                if (!empty($qids)) {
                    $questionBucket = $getBucket($orig, $questionKey);
                    $selQ = array_intersect_key($questionBucket, $qids);
                    if (!empty($selQ)) {
                        $keep[$questionKey] = $selQ;

                        $docKey = $this->firstExistingKey($orig, ['document','Document', \defined('RESOURCE_DOCUMENT') ? RESOURCE_DOCUMENT : '']);
                        if ($docKey) {
                            $docBucket = $getBucket($orig, $docKey);
                            $imageQuizBucket = (isset($docBucket['image_quiz']) && \is_array($docBucket['image_quiz'])) ? $docBucket['image_quiz'] : [];
                            if (!empty($imageQuizBucket)) {
                                $needed = [];
                                foreach ($keep[$questionKey] as $qid => $qwrap) {
                                    $q = (isset($qwrap->obj) && \is_object($qwrap->obj)) ? $qwrap->obj : $qwrap;
                                    $pic = (string) ($q->picture ?? '');
                                    if ('' !== $pic && isset($imageQuizBucket[$pic])) {
                                        $needed[$pic] = true;
                                    }
                                }
                                if (!empty($needed)) {
                                    $keep[$docKey] = $keep[$docKey] ?? [];
                                    $keep[$docKey]['image_quiz'] = array_intersect_key($imageQuizBucket, $needed);
                                }
                            }
                        }
                    }
                }
            } else {
                $this->logDebug('[filterSelection] quizzes selected but no question bucket found');
            }
        }

        // Surveys -> questions (+ invitations)
        $surveyKey = $this->firstExistingKey($orig, ['survey','Survey']);
        if ($surveyKey && !empty($keep[$surveyKey])) {
            $surveyQuestionKey   = $this->firstExistingKey($orig, ['Survey_Question','survey_question', \defined('RESOURCE_SURVEYQUESTION') ? RESOURCE_SURVEYQUESTION : '']);
            $surveyInvitationKey = $this->firstExistingKey($orig, ['Survey_Invitation','survey_invitation', \defined('RESOURCE_SURVEYINVITATION') ? RESOURCE_SURVEYINVITATION : '']);

            if ($surveyQuestionKey) {
                $neededQids   = [];
                $selSurveyIds = array_map('strval', array_keys($keep[$surveyKey]));

                foreach ($keep[$surveyKey] as $sid => $sWrap) {
                    $s = (isset($sWrap->obj) && \is_object($sWrap->obj)) ? $sWrap->obj : $sWrap;
                    if (!empty($s->question_ids) && \is_array($s->question_ids)) {
                        foreach ($s->question_ids as $qid) {
                            $neededQids[(string) $qid] = true;
                        }
                    }
                }
                if (empty($neededQids)) {
                    $surveyQBucket = $getBucket($orig, $surveyQuestionKey);
                    foreach ($surveyQBucket as $qid => $qWrap) {
                        $q = (isset($qWrap->obj) && \is_object($qWrap->obj)) ? $qWrap->obj : $qWrap;
                        $qSurveyId = (string) ($q->survey_id ?? '');
                        if ('' !== $qSurveyId && \in_array($qSurveyId, $selSurveyIds, true)) {
                            $neededQids[(string) $qid] = true;
                        }
                    }
                }
                if (!empty($neededQids)) {
                    $surveyQBucket = $getBucket($orig, $surveyQuestionKey);
                    $keep[$surveyQuestionKey] = array_intersect_key($surveyQBucket, $neededQids);
                }
            } else {
                $this->logDebug('[filterSelection] surveys selected but no question bucket found');
            }

            if ($surveyInvitationKey) {
                $invBucket = $getBucket($orig, $surveyInvitationKey);
                if (!empty($invBucket)) {
                    $neededInv = [];
                    foreach ($invBucket as $iid => $invWrap) {
                        $inv = (isset($invWrap->obj) && \is_object($invWrap->obj)) ? $invWrap->obj : $invWrap;
                        $sid = (string) ($inv->survey_id ?? '');
                        if ('' !== $sid && isset($keep[$surveyKey][$sid])) {
                            $neededInv[(string) $iid] = true;
                        }
                    }
                    if (!empty($neededInv)) {
                        $keep[$surveyInvitationKey] = array_intersect_key($invBucket, $neededInv);
                    }
                }
            }
        }

        // Documents: add parent folders for selected files
        $docKey = $this->firstExistingKey($orig, ['document','Document', \defined('RESOURCE_DOCUMENT') ? RESOURCE_DOCUMENT : '']);
        if ($docKey && !empty($keep[$docKey])) {
            $docBucket = $getBucket($orig, $docKey);

            $foldersByRel = [];
            foreach ($docBucket as $fid => $res) {
                $e = (isset($res->obj) && \is_object($res->obj)) ? $res->obj : $res;
                $ftRaw = strtolower((string) ($e->file_type ?? $e->filetype ?? ''));
                $isFolder = ('folder' === $ftRaw) || (isset($e->path) && substr((string) $e->path, -1) === '/');
                if (!$isFolder) { continue; }

                $p = (string) ($e->path ?? '');
                if ('' === $p) { continue; }

                $frel = '/'.ltrim(substr($p, 8), '/');
                $frel = rtrim($frel, '/').'/';
                if ('//' !== $frel) { $foldersByRel[$frel] = $fid; }
            }

            $needFolderIds = [];
            foreach ($keep[$docKey] as $id => $res) {
                $e = (isset($res->obj) && \is_object($res->obj)) ? $res->obj : $res;
                $ftRaw = strtolower((string) ($e->file_type ?? $e->filetype ?? ''));
                $isFolder = ('folder' === $ftRaw) || (isset($e->path) && substr((string) $e->path, -1) === '/');
                if ($isFolder) { continue; }

                $p = (string) ($e->path ?? '');
                if ('' === $p) { continue; }

                $rel = '/'.ltrim(substr($p, 8), '/');
                $dir = rtrim(\dirname($rel), '/');
                if ('' === $dir) { continue; }

                $acc = '';
                foreach (array_filter(explode('/', $dir)) as $seg) {
                    $acc .= '/'.$seg;
                    $accKey = rtrim($acc, '/').'/';
                    if (isset($foldersByRel[$accKey])) {
                        $needFolderIds[$foldersByRel[$accKey]] = true;
                    }
                }
            }
            if (!empty($needFolderIds)) {
                $added = array_intersect_key($docBucket, $needFolderIds);
                $keep[$docKey] += $added;
            }
        }

        // Links -> pull categories used by the selected links
        $lnkKey = $this->firstExistingKey($orig, ['link','Link', \defined('RESOURCE_LINK') ? RESOURCE_LINK : '']);
        if ($lnkKey && !empty($keep[$lnkKey])) {
            $catIdsUsed = [];
            foreach ($keep[$lnkKey] as $lid => $lWrap) {
                $L = (isset($lWrap->obj) && \is_object($lWrap->obj)) ? $lWrap->obj : $lWrap;
                $cid = (int) ($L->category_id ?? 0);
                if ($cid > 0) { $catIdsUsed[(string) $cid] = true; }
            }

            $catKey = $this->firstExistingKey($orig, ['link_category','Link_Category', \defined('RESOURCE_LINKCATEGORY') ? (string) RESOURCE_LINKCATEGORY : '']);
            if ($catKey && !empty($catIdsUsed)) {
                $catBucket = $getBucket($orig, $catKey);
                if (!empty($catBucket)) {
                    $subset = array_intersect_key($catBucket, $catIdsUsed);
                    $keep[$catKey] = $subset;
                    $keep['link_category'] = $subset; // mirror for convenience
                }
            }
        }

        $keep = array_filter($keep);
        $course->resources = !empty($__metaBuckets) ? ($__metaBuckets + $keep) : $keep;

        $this->logDebug('[filterSelection] non-forum flow end', [
            'selected_types' => array_keys($selected),
            'orig_types'     => array_keys($orig),
            'kept_types'     => array_keys($course->resources ?? []),
        ]);

        return $course;
    }

    /**
     * Map UI options (1/2/3) to legacy file policy.
     */
    private function mapSameNameOption(int $opt): int
    {
        $opt = \in_array($opt, [1, 2, 3], true) ? $opt : 2;

        if (!\defined('FILE_SKIP')) {
            \define('FILE_SKIP', 1);
        }
        if (!\defined('FILE_RENAME')) {
            \define('FILE_RENAME', 2);
        }
        if (!\defined('FILE_OVERWRITE')) {
            \define('FILE_OVERWRITE', 3);
        }

        return match ($opt) {
            1 => FILE_SKIP,
            3 => FILE_OVERWRITE,
            default => FILE_RENAME,
        };
    }

    /**
     * Set debug mode from Request (query/header).
     */
    private function setDebugFromRequest(?Request $req): void
    {
        if (!$req) {
            return;
        }
        // Query param wins
        if ($req->query->has('debug')) {
            $this->debug = $req->query->getBoolean('debug');

            return;
        }
        // Fallback to header
        $hdr = $req->headers->get('X-Debug');
        if (null !== $hdr) {
            $val = trim((string) $hdr);
            $this->debug = ('' !== $val && '0' !== $val && 0 !== strcasecmp($val, 'false'));
        }
    }

    /**
     * Debug logger with stage + compact JSON payload.
     */
    private function logDebug(string $stage, mixed $payload = null): void
    {
        if (!$this->debug) {
            return;
        }
        $prefix = 'COURSE_DEBUG';
        if (null === $payload) {
            error_log("$prefix: $stage");

            return;
        }
        // Safe/short json
        $json = null;

        try {
            $json = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
            if (null !== $json && \strlen($json) > 8000) {
                $json = substr($json, 0, 8000).'…(truncated)';
            }
        } catch (Throwable $e) {
            $json = '[payload_json_error: '.$e->getMessage().']';
        }
        error_log("$prefix: $stage -> $json");
    }

    /**
     * Snapshot of resources bag for quick inspection.
     */
    private function snapshotResources(object $course, int $maxTypes = 20, int $maxItemsPerType = 3): array
    {
        $out = [];
        $res = \is_array($course->resources ?? null) ? $course->resources : [];
        $i = 0;
        foreach ($res as $type => $bag) {
            if ($i++ >= $maxTypes) {
                $out['__notice'] = 'types truncated';

                break;
            }
            $snap = ['count' => \is_array($bag) ? \count($bag) : 0, 'sample' => []];
            if (\is_array($bag)) {
                $j = 0;
                foreach ($bag as $id => $obj) {
                    if ($j++ >= $maxItemsPerType) {
                        $snap['sample'][] = ['__notice' => 'truncated'];

                        break;
                    }
                    $entity = (\is_object($obj) && isset($obj->obj) && \is_object($obj->obj)) ? $obj->obj : $obj;
                    $snap['sample'][] = [
                        'id' => (string) $id,
                        'cls' => \is_object($obj) ? $obj::class : \gettype($obj),
                        'entity_keys' => \is_object($entity) ? \array_slice(array_keys((array) $entity), 0, 12) : [],
                    ];
                }
            }
            $out[(string) $type] = $snap;
        }

        return $out;
    }

    /**
     * Snapshot of forum-family counters.
     */
    private function snapshotForumCounts(object $course): array
    {
        $r = \is_array($course->resources ?? null) ? $course->resources : [];
        $get = fn ($a, $b) => \is_array($r[$a] ?? $r[$b] ?? null) ? \count($r[$a] ?? $r[$b]) : 0;

        return [
            'Forum_Category' => $get('Forum_Category', 'forum_category'),
            'forum' => $get('forum', 'Forum'),
            'thread' => $get('thread', 'forum_topic'),
            'post' => $get('post', 'forum_post'),
        ];
    }

    /**
     * Builds the selection map [type => [id => true]] from high-level types.
     * Assumes that hydrateLpDependenciesFromSnapshot() has already been called, so
     * $course->resources contains LP + necessary dependencies (docs, links, quiz, etc.).
     *
     * @param object   $course        Legacy Course with already hydrated resources
     * @param string[] $selectedTypes Types marked by the UI (e.g., ['learnpath'])
     *
     * @return array<string, array<int|string, bool>>
     */
    private function buildSelectionFromTypes(object $course, array $selectedTypes): array
    {
        $selectedTypes = array_map(
            fn ($t) => $this->normalizeTypeKey((string) $t),
            $selectedTypes
        );

        $res = \is_array($course->resources ?? null) ? $course->resources : [];

        $coreDeps = [
            'document', 'link', 'quiz', 'work', 'survey',
            'Forum_Category', 'forum', 'thread', 'post',
            'exercise_question', 'survey_question', 'link_category',
        ];

        $presentKeys = array_fill_keys(array_map(
            fn ($k) => $this->normalizeTypeKey((string) $k),
            array_keys($res)
        ), true);

        $out = [];

        $addBucket = function (string $typeKey) use (&$out, $res): void {
            if (!isset($res[$typeKey]) || !\is_array($res[$typeKey]) || empty($res[$typeKey])) {
                return;
            }
            $ids = [];
            foreach ($res[$typeKey] as $id => $_) {
                $ids[(string) $id] = true;
            }
            if ($ids) {
                $out[$typeKey] = $ids;
            }
        };

        foreach ($selectedTypes as $t) {
            $addBucket($t);

            if ('learnpath' === $t) {
                foreach ($coreDeps as $depRaw) {
                    $dep = $this->normalizeTypeKey($depRaw);
                    if (isset($presentKeys[$dep])) {
                        $addBucket($dep);
                    }
                }
            }
        }

        $this->logDebug('[buildSelectionFromTypes] built', [
            'selectedTypes' => $selectedTypes,
            'kept_types' => array_keys($out),
        ]);

        return $out;
    }

    /**
     * Build link tree (Category → Link) for the UI.
     * Categories are not selectable; links are leaves (item_count = 0).
     */
    private function buildLinkTreeForVue(object $course, string $groupTitle): array
    {
        $this->logDebug('[buildLinkTreeForVue] start');

        $res = \is_array($course->resources ?? null) ? $course->resources : [];
        $catRaw  = $res['link_category'] ?? $res['Link_Category'] ?? [];
        $linkRaw = $res['link']          ?? $res['Link']          ?? [];

        $this->logDebug('[buildLinkTreeForVue] raw counts', [
            'categories' => \is_array($catRaw) ? \count($catRaw) : 0,
            'links'      => \is_array($linkRaw) ? \count($linkRaw) : 0,
        ]);

        $cats = [];
        foreach ($catRaw as $id => $obj) {
            $id = (int) $id;
            if ($id <= 0 || !\is_object($obj)) { continue; }
            $e = $this->objectEntity($obj);
            $label = $this->resolveItemLabel('link_category', $e, $id);
            $cats[$id] = [
                'id'           => $id,
                'type'         => 'link_category',
                'label'        => (($label !== '' ? $label : ('Category #'.$id)).'/'),
                'selectable'   => true,
                'items'        => [],
                'has_children' => false,
                'item_count'   => 0,
                'extra'        => ['filetype' => 'folder'],
            ];
        }

        // Virtual "Uncategorized"
        $uncatKey = -9999;
        if (!isset($cats[$uncatKey])) {
            $cats[$uncatKey] = [
                'id'           => $uncatKey,
                'type'         => 'link_category',
                'label'        => 'Uncategorized/',
                'selectable'   => true,
                'items'        => [],
                '_virtual'     => true,
                'has_children' => false,
                'item_count'   => 0,
                'extra'        => ['filetype' => 'folder'],
            ];
        }

        // Assign links to categories
        foreach ($linkRaw as $id => $obj) {
            $id = (int) $id;
            if ($id <= 0 || !\is_object($obj)) { continue; }
            $e = $this->objectEntity($obj);

            $cid = (int) ($e->category_id ?? 0);
            if (!isset($cats[$cid])) { $cid = $uncatKey; }

            $cats[$cid]['items'][] = [
                'id'         => $id,
                'type'       => 'link',
                'label'      => $this->resolveItemLabel('link', $e, $id),
                'extra'      => $this->buildExtra('link', $e) ?: new \stdClass(),
                'selectable' => true,
                'item_count' => 0,
            ];
        }

        // Drop empty virtual category, sort, and finalize UI hints
        $catNodes = array_values(array_filter($cats, static function ($c) {
            if (!empty($c['_virtual']) && empty($c['items'])) { return false; }
            return true;
        }));

        foreach ($catNodes as &$c) {
            if (!empty($c['items'])) {
                usort($c['items'], static fn ($a, $b) => strcasecmp((string) $a['label'], (string) $b['label']));
            }
            $c['has_children'] = !empty($c['items']);
            $c['item_count']   = \count($c['items'] ?? []);
        }
        unset($c);

        usort($catNodes, static fn ($a, $b) => strcasecmp((string) $a['label'], (string) $b['label']));

        $this->logDebug('[buildLinkTreeForVue] end', ['categories' => \count($catNodes)]);

        return [
            'type'  => 'link',
            'title' => $groupTitle,
            'items' => $catNodes,
        ];
    }

    /**
     * Leaves only the items selected by the UI in $course->resources.
     * Expects $selected with the following form:
     * [
     * "documents" => ["123" => true, "124" => true],
     * "links" => ["7" => true],
     * "quiz" => ["45" => true],
     * ...
     * ].
     */
    private function filterCourseResources(object $course, array $selected): void
    {
        if (!isset($course->resources) || !\is_array($course->resources)) {
            return;
        }

        $typeMap = [
            'documents' => RESOURCE_DOCUMENT,
            'links' => RESOURCE_LINK,
            'quizzes' => RESOURCE_QUIZ,
            'quiz' => RESOURCE_QUIZ,
            'quiz_questions' => RESOURCE_QUIZQUESTION,
            'surveys' => RESOURCE_SURVEY,
            'survey' => RESOURCE_SURVEY,
            'survey_questions' => RESOURCE_SURVEYQUESTION,
            'announcement' => RESOURCE_ANNOUNCEMENT,
            'events' => RESOURCE_EVENT,
            'course_description' => RESOURCE_COURSEDESCRIPTION,
            'glossary' => RESOURCE_GLOSSARY,
            'wiki' => RESOURCE_WIKI,
            'thematic' => RESOURCE_THEMATIC,
            'attendance' => RESOURCE_ATTENDANCE,
            'works' => RESOURCE_WORK,
            'gradebook' => RESOURCE_GRADEBOOK,
            'learnpaths' => RESOURCE_LEARNPATH,
            'learnpath_category' => RESOURCE_LEARNPATH_CATEGORY,
            'tool_intro' => RESOURCE_TOOL_INTRO,
            'forums' => RESOURCE_FORUM,
            'forum' => RESOURCE_FORUM,
            'forum_topic' => RESOURCE_FORUMTOPIC,
            'forum_post' => RESOURCE_FORUMPOST,
        ];

        $allowed = [];
        foreach ($selected as $k => $idsMap) {
            $key = $typeMap[$k] ?? $k;
            $allowed[$key] = array_fill_keys(array_map('intval', array_keys((array) $idsMap)), true);
        }

        foreach ($course->resources as $rtype => $bucket) {
            if (!isset($allowed[$rtype])) {
                continue;
            }
            $keep = $allowed[$rtype];
            $filtered = [];
            foreach ((array) $bucket as $id => $obj) {
                $iid = (int) ($obj->source_id ?? $id);
                if (isset($keep[$iid])) {
                    $filtered[$id] = $obj;
                }
            }
            $course->resources[$rtype] = $filtered;
        }
    }

    /**
     * Resolve absolute path of a backupId inside the backups directory, with safety checks.
     */
    private function resolveBackupPath(string $backupId): string
    {
        $base = rtrim((string) CourseArchiver::getBackupDir(), DIRECTORY_SEPARATOR);
        $baseReal = realpath($base) ?: $base;

        $file = basename($backupId);
        $path = $baseReal . DIRECTORY_SEPARATOR . $file;

        $real = realpath($path);

        if ($real !== false && strncmp($real, $baseReal, strlen($baseReal)) === 0) {
            return $real;
        }

        return $path;
    }

    /**
     * Load a legacy Course object from any backup:
     * - Chamilo (.zip with course_info.dat) → CourseArchiver::readCourse() or lenient fallback (your original logic)
     * - Moodle (.mbz/.tgz/.gz or ZIP with moodle_backup.xml) → MoodleImport builder
     *
     * IMPORTANT:
     * - Keeps your original Chamilo flow intact (strict → fallback manual decode/unserialize).
     * - Tries Moodle only when the package looks like Moodle.
     * - Adds __meta.import_source = "chamilo" | "moodle" for downstream logic.
     */
    private function loadLegacyCourseForAnyBackup(string $backupId, string $force = 'auto'): object
    {
        $path = $this->resolveBackupPath($backupId);

        $force = strtolower($force);
        if ('dat' === $force || 'chamilo' === $force) {
            $looksMoodle = false;
            $preferChamilo = true;
        } elseif ('moodle' === $force) {
            $looksMoodle = true;
            $preferChamilo = false;
        } else {
            $looksMoodle   = $this->isMoodleByExt($path) || $this->zipHasMoodleBackupXml($path);
            $preferChamilo = $this->zipHasCourseInfoDat($path);
        }

        if ($preferChamilo || !$looksMoodle) {
            CourseArchiver::setDebug($this->debug);

            try {
                $course = CourseArchiver::readCourse($backupId, false);
                if (\is_object($course)) {
                    // … (resto igual)
                    if (!isset($course->resources) || !\is_array($course->resources)) { $course->resources = []; }
                    $course->resources['__meta'] = (array) ($course->resources['__meta'] ?? []);
                    $course->resources['__meta']['import_source'] = 'chamilo';
                    return $course;
                }
            } catch (\Throwable $e) {
                $this->logDebug('[loadLegacyCourseForAnyBackup] readCourse() failed', ['error' => $e->getMessage()]);
            }

            $zipPath = $this->resolveBackupPath($backupId);
            $ci = $this->readCourseInfoFromZip($zipPath);
            if (empty($ci['ok'])) {
                if ($looksMoodle) {
                    $this->logDebug('[loadLegacyCourseForAnyBackup] no course_info.dat, trying MoodleImport as last resort');
                    return $this->loadMoodleCourseOrFail($path);
                }
                throw new RuntimeException('course_info.dat not found in backup');
            }

            $raw = (string) $ci['data'];
            $payload = base64_decode($raw, true);
            if ($payload === false) { $payload = $raw; }

            $payload = CourseArchiver::preprocessSerializedPayloadForTypedProps($payload);
            CourseArchiver::ensureLegacyAliases();

            set_error_handler(static function () {});
            try {
                if (class_exists(\UnserializeApi::class)) {
                    $c = \UnserializeApi::unserialize('course', $payload);
                } else {
                    $c = @unserialize($payload, ['allowed_classes' => true]);
                }
            } finally {
                restore_error_handler();
            }

            if (!\is_object($c ?? null)) {
                if ($looksMoodle) {
                    $this->logDebug('[loadLegacyCourseForAnyBackup] Chamilo fallback failed, trying MoodleImport');
                    return $this->loadMoodleCourseOrFail($path);
                }
                throw new RuntimeException('Could not unserialize course (fallback)');
            }

            if (!isset($c->resources) || !\is_array($c->resources)) { $c->resources = []; }

The variable $c does not seem to be defined for all execution paths leading up to this point.

            $c->resources['__meta'] = (array) ($c->resources['__meta'] ?? []);
            $c->resources['__meta']['import_source'] = 'chamilo';

            return $c;
        }

        // Moodle path
        if ($looksMoodle) {
            $this->logDebug('[loadLegacyCourseForAnyBackup] using MoodleImport');
            return $this->loadMoodleCourseOrFail($path);
        }

        throw new RuntimeException('Unsupported package: neither course_info.dat nor moodle_backup.xml found.');
    }

    /**
     * Normalize resource buckets to the exact keys supported by CourseRestorer.
     * Only the canonical keys below are produced; common aliases are mapped.
     * - Never drop data: merge buckets; keep __meta as-is.
     * - Make sure "document" survives if it existed before.
     */
    private function normalizeBucketsForRestorer(object $course): void
    {
        if (!isset($course->resources) || !\is_array($course->resources)) {
            return;
        }

        // Split meta buckets
        $all = $course->resources;
        $meta = [];
        foreach ($all as $k => $v) {
            if (\is_string($k) && str_starts_with($k, '__')) {
                $meta[$k] = $v;
                unset($all[$k]);
            }
        }

        // Start from current
        $out = $all;

        // merge array buckets preserving numeric/string ids
        $merge = static function (array $dst, array $src): array {
            foreach ($src as $id => $obj) {
                if (!\array_key_exists($id, $dst)) {
                    $dst[$id] = $obj;
                }
            }
            return $dst;
        };

        // safe alias map (input -> canonical). Extend only if needed.
        $aliases = [
            // documents
            'documents'          => 'document',
            'Document'           => 'document',
            'document '          => 'document',

            // tool intro
            'tool introduction'    => 'tool_intro',
            'tool_introduction'    => 'tool_intro',
            'tool/introduction'    => 'tool_intro',
            'tool intro'           => 'tool_intro',
            'Tool introduction'    => 'tool_intro',

            // forums
            'forums'             => 'forum',
            'Forum'              => 'forum',
            'Forum_Category'     => 'forum_category',
            'forumcategory'      => 'forum_category',
            'thread'             => 'forum_topic',
            'Thread'             => 'forum_topic',
            'forumtopic'         => 'forum_topic',
            'post'               => 'forum_post',
            'Post'               => 'forum_post',
            'forumpost'          => 'forum_post',

            // links
            'links'              => 'link',
            'link category'      => 'link_category',

            // quiz + questions
            'Exercise_Question'  => 'exercise_question',
            'exercisequestion'   => 'exercise_question',

            // surveys
            'surveys'            => 'survey',
            'surveyquestion'     => 'survey_question',

            // announcements
            'announcements'      => 'announcement',
            'Announcements'      => 'announcement',
        ];

        // Normalize keys (case/spacing) and apply alias merges
        foreach ($all as $rawKey => $_bucket) {
            if (!\is_array($_bucket)) {
                continue; // defensive
            }
            $k = (string) $rawKey;
            $norm = strtolower(trim(strtr($k, ['\\' => '/', '-' => '_'])));
            $norm2 = str_replace('/', '_', $norm);

            $canonical = null;
            if (isset($aliases[$norm])) {
                $canonical = $aliases[$norm];
            } elseif (isset($aliases[$norm2])) {
                $canonical = $aliases[$norm2];
            }

            if ($canonical && $canonical !== $rawKey) {
                // Merge into canonical and drop the alias key
                $out[$canonical] = isset($out[$canonical]) && \is_array($out[$canonical])
                    ? $merge($out[$canonical], $_bucket)
                    : $_bucket;
                unset($out[$rawKey]);
            }
            // else: leave as-is (pass-through)
        }

        // Safety: if there was any docs bucket under an alias, ensure 'document' is present.
        if (!isset($out['document'])) {
            if (isset($all['documents']) && \is_array($all['documents'])) {
                $out['document'] = $all['documents'];
            } elseif (isset($all['Document']) && \is_array($all['Document'])) {
                $out['document'] = $all['Document'];
            }
        }

        // Gentle ordering for readability only (does not affect presence)
        $order = [
            'announcement', 'document', 'link', 'link_category',
            'forum', 'forum_category', 'forum_topic', 'forum_post',
            'quiz', 'exercise_question',
            'survey', 'survey_question',
            'learnpath', 'tool_intro',
            'work',
        ];
        $w = [];
        foreach ($order as $i => $key) { $w[$key] = $i; }
        uksort($out, static function ($a, $b) use ($w) {
            $wa = $w[$a] ?? 9999;
            $wb = $w[$b] ?? 9999;
            return $wa <=> $wb ?: strcasecmp((string) $a, (string) $b);
        });

        // Final assign: meta first, then normalized buckets
        $course->resources = $meta + $out;

        // Debug trace to verify we didn't lose keys
        $this->logDebug('[normalizeBucketsForRestorer] final keys', array_keys((array) $course->resources));
    }

    /**
     * Read import_source without depending on filtered resources.
     * Falls back to $course->info['__import_source'] if needed.
     */
    private function getImportSource(object $course): string
    {
        $src = strtolower((string) ($course->resources['__meta']['import_source'] ?? ''));
        if ('' !== $src) {
            return $src;
        }

        // Fallbacks (defensive)
        return strtolower((string) ($course->info['__import_source'] ?? ''));
    }

    /**
     * Builds a CC 1.3 preview from the legacy Course (only the implemented one).
     * Returns a structure intended for rendering/committing before the actual export.
     */
    private function buildCc13Preview(object $course): array
    {
        $ims = [
            'supportedTypes' => Cc13Capabilities::exportableTypes(), // ['document']
            'resources' => [
                'webcontent' => [],
            ],
            'counts' => ['files' => 0, 'folders' => 0],
            'defaultSelection' => [
                'documents' => [],
            ],
        ];

        $res = \is_array($course->resources ?? null) ? $course->resources : [];
        $docKey = null;

        foreach (['document', 'Document', \defined('RESOURCE_DOCUMENT') ? RESOURCE_DOCUMENT : ''] as $cand) {
            if ($cand && isset($res[$cand]) && \is_array($res[$cand]) && !empty($res[$cand])) {
                $docKey = $cand;
                break;
            }
        }
        if (!$docKey) {
            return $ims;
        }

        foreach ($res[$docKey] as $iid => $wrap) {
            if (!\is_object($wrap)) {
                continue;
            }
            $e = (isset($wrap->obj) && \is_object($wrap->obj)) ? $wrap->obj : $wrap;

            $rawPath = (string) ($e->path ?? $e->full_path ?? '');
            if ('' === $rawPath) {
                continue;
            }
            $rel = ltrim(preg_replace('~^/?document/?~', '', $rawPath), '/');

            $fileType = strtolower((string) ($e->file_type ?? $e->filetype ?? ''));
            $isDir = ($fileType === 'folder') || (substr($rawPath, -1) === '/');

            $title = (string) ($e->title ?? $wrap->name ?? basename($rel));
            $ims['resources']['webcontent'][] = [
                'id' => (int) $iid,
                'cc_type' => 'webcontent',
                'title' => $title !== '' ? $title : basename($rel),
                'rel' => $rel,
                'is_dir' => $isDir,
                'would_be_manifest_entry' => !$isDir,
            ];

            if (!$isDir) {
                $ims['defaultSelection']['documents'][(int) $iid] = true;
                $ims['counts']['files']++;
            } else {
                $ims['counts']['folders']++;
            }
        }

        return $ims;
    }

    /**
     * Expand category selections (link/forum) to their item IDs using a full course snapshot.
     * Returns ['documents'=>[id=>true], 'links'=>[id=>true], 'forums'=>[id=>true]] merged with $normSel.
     */
    private function expandCc13SelectionFromCategories(object $course, array $normSel): array
    {
        $out = [
            'documents' => (array) ($normSel['documents'] ?? []),
            'links'     => (array) ($normSel['links']     ?? []),
            'forums'    => (array) ($normSel['forums']    ?? []),
        ];

        $res = \is_array($course->resources ?? null) ? $course->resources : [];

        // Link categories → link IDs
        if (!empty($normSel['link_category']) && \is_array($res['link'] ?? $res['Link'] ?? null)) {
            $selCats = array_fill_keys(array_map('strval', array_keys($normSel['link_category'])), true);
            $links   = $res['link'] ?? $res['Link'];
            foreach ($links as $lid => $wrap) {
                if (!\is_object($wrap)) { continue; }
                $e = (isset($wrap->obj) && \is_object($wrap->obj)) ? $wrap->obj : $wrap;
                $cid = (string) (int) ($e->category_id ?? 0);
                if (isset($selCats[$cid])) { $out['links'][(string)$lid] = true; }
            }
        }

        // Forum categories → forum IDs
        if (!empty($normSel['forum_category']) && \is_array($res['forum'] ?? $res['Forum'] ?? null)) {
            $selCats = array_fill_keys(array_map('strval', array_keys($normSel['forum_category'])), true);
            $forums  = $res['forum'] ?? $res['Forum'];
            foreach ($forums as $fid => $wrap) {
                if (!\is_object($wrap)) { continue; }
                $e = (isset($wrap->obj) && \is_object($wrap->obj)) ? $wrap->obj : $wrap;
                $cid = (string) (int) ($e->forum_category ?? $e->forum_category_id ?? $e->category_id ?? 0);
                if (isset($selCats[$cid])) { $out['forums'][(string)$fid] = true; }
            }
        }

        return $out;
    }

    /**
     * Infer tool buckets required by a given selection payload (used in 'selected' scope).
     *
     * Expected selection items like: { "type": "document"|"quiz"|"survey"|... , "id": <int> }
     *
     * @param array<int,array<string,mixed>> $selected
     * @return string[]
     */
    private function inferToolsFromSelection(array $selected): array
    {
        $has = static fn(string $k): bool =>
            !empty($selected[$k]) && \is_array($selected[$k]) && \count($selected[$k]) > 0;

        $want = [];

        // documents
        if ($has('document')) {
            $want[] = 'documents';
        }

        // links (categories imply links too)
        if ($has('link') || $has('link_category')) {
            $want[] = 'links';
        }

        // forums (any of the family implies forums)
        if ($has('forum') || $has('forum_category') || $has('forum_topic') || $has('thread') || $has('post') || $has('forum_post')) {
            $want[] = 'forums';
        }

        // quizzes / questions
        if ($has('quiz') || $has('exercise') || $has('exercise_question')) {
            $want[] = 'quizzes';
            $want[] = 'quiz_questions';
        }

        // surveys / questions / invitations
        if ($has('survey') || $has('survey_question') || $has('survey_invitation')) {
            $want[] = 'surveys';
            $want[] = 'survey_questions';
        }

        // learnpaths
        if ($has('learnpath') || $has('learnpath_category')) {
            $want[] = 'learnpaths';
            $want[] = 'learnpath_category';
        }

        // others
        if ($has('work'))     { $want[] = 'works'; }
        if ($has('glossary')) { $want[] = 'glossary'; }
        if ($has('tool_intro')) { $want[] = 'tool_intro'; }
        if ($has('attendance')) { $want[] = 'attendance'; }
        if ($has('announcement')) { $want[] = 'announcement'; }
        if ($has('calendar_event')) { $want[] = 'events'; }
        if ($has('wiki')) { $want[] = 'wiki'; }
        if ($has('thematic')) { $want[] = 'thematic'; }
        if ($has('gradebook')) { $want[] = 'gradebook'; }

        if ($has('course_descriptions') || $has('course_description')) { $tools[] = 'course_descriptions'; }

$tools was never initialized. Although not strictly required by PHP, it is generally a good practice to add $tools = array(); before regardless.

        // Dedup
        return array_values(array_unique(array_filter($want)));
    }

    private function intersectBucketByIds(array $bucket, array $idsMap): array
    {
        $out = [];
        foreach ($bucket as $id => $obj) {
            $ent = (isset($obj->obj) && \is_object($obj->obj)) ? $obj->obj : $obj;
            $k1  = (string) $id;
            $k2  = (string) ($ent->source_id ?? $obj->source_id ?? '');
            if (isset($idsMap[$k1]) || ($k2 !== '' && isset($idsMap[$k2]))) {
                $out[$id] = $obj;
            }
        }
        return $out;
    }

    private function bucketKeyCandidates(string $type): array
    {
        $t = $this->normalizeTypeKey($type);

        // Constants (string values) if defined
        $RD  = \defined('RESOURCE_DOCUMENT')       ? (string) RESOURCE_DOCUMENT       : '';
        $RL  = \defined('RESOURCE_LINK')           ? (string) RESOURCE_LINK           : '';
        $RF  = \defined('RESOURCE_FORUM')          ? (string) RESOURCE_FORUM          : '';
        $RFT = \defined('RESOURCE_FORUMTOPIC')     ? (string) RESOURCE_FORUMTOPIC     : '';
        $RFP = \defined('RESOURCE_FORUMPOST')      ? (string) RESOURCE_FORUMPOST      : '';
        $RQ  = \defined('RESOURCE_QUIZ')           ? (string) RESOURCE_QUIZ           : '';
        $RQQ = \defined('RESOURCE_QUIZQUESTION')   ? (string) RESOURCE_QUIZQUESTION   : '';
        $RS  = \defined('RESOURCE_SURVEY')         ? (string) RESOURCE_SURVEY         : '';
        $RSQ = \defined('RESOURCE_SURVEYQUESTION') ? (string) RESOURCE_SURVEYQUESTION : '';

        $map = [
            'document'         => ['document', 'Document', $RD],
            'link'             => ['link', 'Link', $RL],
            'link_category'    => ['link_category', 'Link_Category'],
            'forum'            => ['forum', 'Forum', $RF],
            'forum_category'   => ['forum_category', 'Forum_Category'],
            'forum_topic'      => ['forum_topic', 'thread', $RFT],
            'forum_post'       => ['forum_post', 'post', $RFP],
            'quiz'             => ['quiz', 'Quiz', $RQ],
            'exercise_question'=> ['Exercise_Question', 'exercise_question', $RQQ],
            'survey'           => ['survey', 'Survey', $RS],
            'survey_question'  => ['Survey_Question', 'survey_question', $RSQ],
            'tool_intro'       => ['tool_intro', 'Tool introduction'],
        ];

        $c = $map[$t] ?? [$t, ucfirst($t)];
        return array_values(array_filter($c, static fn($x) => $x !== ''));
    }

    private function findBucketKey(array $res, string $type): ?string
    {
        $key = $this->firstExistingKey($res, $this->bucketKeyCandidates($type));
        return $key !== null ? (string) $key : null;
    }

    private function findBucket(array $res, string $type): array
    {
        $k = $this->findBucketKey($res, $type);
        return ($k !== null && isset($res[$k]) && \is_array($res[$k])) ? $res[$k] : [];
    }

    /** True if file extension suggests a Moodle backup. */
    private function isMoodleByExt(string $path): bool
    {
        $ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));
        return in_array($ext, ['mbz','tgz','gz'], true);
    }

    /** Quick ZIP probe for 'moodle_backup.xml'. Safe no-op for non-zip files. */
    private function zipHasMoodleBackupXml(string $path): bool
    {
        $ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));
        // Many .mbz are plain ZIPs; try to open if extension is zip/mbz
        if (!in_array($ext, ['zip','mbz'], true)) {
            return false;
        }
        $zip = new \ZipArchive();
        if (true !== ($err = $zip->open($path))) {
            return false;
        }
        $idx = $zip->locateName('moodle_backup.xml', \ZipArchive::FL_NOCASE);
        $zip->close();
        return ($idx !== false);
    }

    /** Quick ZIP probe for 'course_info.dat'. Safe no-op for non-zip files. */
    private function zipHasCourseInfoDat(string $path): bool
    {
        $ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));
        if (!in_array($ext, ['zip','mbz'], true)) {
            return false;
        }
        $zip = new \ZipArchive();
        if (true !== ($err = $zip->open($path))) {
            return false;
        }
        // common locations
        foreach (['course_info.dat','course/course_info.dat','backup/course_info.dat'] as $cand) {
            $idx = $zip->locateName($cand, \ZipArchive::FL_NOCASE);
            if ($idx !== false) { $zip->close(); return true; }
        }
        $zip->close();
        return false;
    }

    /**
     * Build legacy Course graph from a Moodle archive and set __meta.import_source.
     * Throws RuntimeException on failure.
     */
    private function loadMoodleCourseOrFail(string $absPath): object
    {
        if (!class_exists(MoodleImport::class)) {
            throw new RuntimeException('MoodleImport class not available');
        }
        $importer = new MoodleImport(debug: $this->debug);

        if (!method_exists($importer, 'buildLegacyCourseFromMoodleArchive')) {
            throw new RuntimeException('MoodleImport::buildLegacyCourseFromMoodleArchive() not available');
        }

        $course = $importer->buildLegacyCourseFromMoodleArchive($absPath);

        if (!\is_object($course) || empty($course->resources) || !\is_array($course->resources)) {
            throw new RuntimeException('Moodle backup contains no importable resources');
        }

        $course->resources['__meta'] = (array) ($course->resources['__meta'] ?? []);
        $course->resources['__meta']['import_source'] = 'moodle';

        return $course;
    }

    /**
     * Clone a course snapshot keeping only the allowed buckets (preserving original-case keys).
     * This is a shallow clone of the course object with a filtered 'resources' array.
     */
    private function cloneCourseWithBuckets(object $course, array $allowed): object
    {
        $clone = clone $course;

        if (!isset($course->resources) || !\is_array($course->resources)) {
            $clone->resources = [];
            return $clone;
        }

        // Build a lookup based on the original-case keys present in $allowed
        $allowedLookup = array_flip($allowed);

        // Intersect by original-case keys
        $clone->resources = array_intersect_key($course->resources, $allowedLookup);

        return $clone;
    }

    /**
     * Generic runner for a bucket group: checks if it was requested, extracts present snapshot keys,
     * appends legacy constant keys (if defined), and delegates to MoodleImport::restoreSelectedBuckets().
     *
     * Returns:
     *   - array stats when executed,
     *   - ['imported'=>0,'notes'=>['No ... buckets']] when requested but none present,
     *   - null when not requested at all.
     */
    private function runBucketRestore(
        MoodleImport           $importer,
        array                  $requestedNormalized,
        array                  $requestAliases,
        array                  $snapshotAliases,
        array                  $legacyConstNames,
        object                 $course,
        string                 $backupPath,
        EntityManagerInterface $em,
        int                    $cid,
        int                    $sid,
        int                    $sameFileNameOption,
        string $statKey
    ): ?array {
        // Normalize request aliases and check if intersect
        $norm = static fn(string $k): string => strtolower((string) $k);
        $reqSet = array_map($norm, $requestAliases);

        if (count(array_intersect($requestedNormalized, $reqSet)) === 0) {
            // Not requested -> skip quietly
            return null;
        }

        // Gather snapshot-present keys
        $resources = (array) ($course->resources ?? []);
        $present = array_keys($resources);
        $presentNorm = array_map($norm, $present);

        $snapWanted = array_map($norm, $snapshotAliases);
        $allowed = [];
        foreach ($present as $idx => $origKey) {
            if (in_array($presentNorm[$idx], $snapWanted, true)) {
                $allowed[] = $origKey; // keep original key casing as in snapshot
            }
        }

        // Add legacy constant-based keys if defined
        foreach ($legacyConstNames as $c) {
            if (\defined($c)) {
                $allowed[] = (string) \constant($c);
            }
        }

        // Deduplicate + sanitize
        $allowed = array_values(array_unique(array_filter($allowed, static fn($v) => \is_string($v) && $v !== '')));

        // Quick clone of the course with only these buckets
        $courseForThis = $this->cloneCourseWithBuckets($course, $allowed);

        if (empty((array) ($courseForThis->resources ?? []))) {
            $this->logDebug("[runBucketRestore] {$statKey} skipped (no matching buckets present)", [
                'requested' => $requestAliases,
                'snapshot_aliases' => $snapshotAliases,
                'legacy' => $legacyConstNames,
                'available' => array_keys((array) $course->resources),
            ]);
            return ['imported' => 0, 'notes' => ["No {$statKey} buckets"]];
        }

        if (\method_exists($importer, 'attachContext')) {
            // Optional internal context
            $importer->attachContext($backupPath, $em, $cid, $sid, $sameFileNameOption);
        }

        // Delegate with stable signature
        return $importer->restoreSelectedBuckets(
            $backupPath,
            $em,
            $cid,
            $sid,
            $allowed,
            $courseForThis
        );
    }
}